skip to content

Devcontainer Configuration

A Codespace is only as good as its devcontainer.json — the file that pins the image, the tooling features, and the setup commands so every contributor gets an identical environment. Prebuilds are what turn a five-minute cold start into seconds.

on this pageshow

questions

6

In GitHub Codespaces, where can a repository's devcontainer.json live, and what does a codespace use when there is none?

level: juniorimportance: must knowfreq 38%

answer

  1. a hidden folder at the root
  2. leading period when at the root
  3. one subfolder per alternative
  4. nothing inherited between files
  5. a default image full of runtimes

basics

~10 s

Codespaces reads .devcontainer/devcontainer.json or a root-level .devcontainer.json, plus alternatives at .devcontainer/NAME/devcontainer.json chosen at creation. With no configuration, it uses a default Linux image with common runtimes and tools.

solid answer

~50 s

The usual home is `.devcontainer/devcontainer.json`. A single file may instead sit at the repository root, but then its name must start with a period: `.devcontainer.json`. To offer a choice, put each alternative in its own subfolder, `.devcontainer/SUBFOLDER/devcontainer.json`; whoever creates the codespace picks one, and each codespace is built from exactly one file, because settings are never imported or inherited between files, so keep each file's Dockerfile and scripts beside it. Branches can carry different configurations. With no configuration at all, Codespaces falls back to its default dev container configuration: a Linux image with recent runtimes for many popular languages, Git, the GitHub CLI and other common tools. The file is JSONC, so comments are allowed. An edit affects codespaces created afterwards; an existing codespace picks it up only after you pull the change and rebuild its container.

go deeper

for a junior

Recall the two single-file locations, the subfolder rule for alternatives, and that a repository with no file still gets a codespace from the default image.

for a middle

Explain why alternatives cannot share settings, how a creator picks one, and why an existing codespace needs a rebuild before a committed change reaches it.

for a senior

Show how you split a large repository into per-team configurations, keep each self-contained, and test a configuration change in a codespace before it reaches a busy branch.

for a principal

Weigh the default image's convenience against a pinned, committed configuration, and decide how many alternative configurations a repository can carry before upkeep outweighs the benefit.

## What devcontainer.json is Every codespace is a **dev container**: a Docker container, running on a virtual machine dedicated to that codespace, that holds the project's tools and has the cloned repository mounted into it. The file that describes that container is `devcontainer.json`. It names where the container comes from (an image, a Dockerfile or a Docker Compose file), which **features** to add, which commands to run as the container is set up, and how the editor should be configured. Because it is committed to the repository, everyone who opens a codespace on that branch gets the same environment. The format is **JSONC** (JSON with comments). Comments are legal, so a linter must be set to JSONC rather than strict JSON or it will flag every comment as an error. ## Where Codespaces looks | Path | When to use it | |---|---| | `.devcontainer/devcontainer.json` | The normal location; the Dockerfile and scripts usually sit beside it | | `.devcontainer.json` at the repository root | A single configuration with no folder; the leading period is required | | `.devcontainer/SUBFOLDER/devcontainer.json` | Each alternative configuration, one per subfolder | A file called plain `devcontainer.json` at the repository root is **not** one of these locations. The root form only works with the leading period. ## Several configurations in one repository Large repositories often serve several teams, so one environment rarely fits everyone. Codespaces handles this with alternative files: - Each alternative lives in its own subfolder, for example `.devcontainer/web/devcontainer.json` and `.devcontainer/api/devcontainer.json`. - When more than one exists, the person creating the codespace chooses a configuration from the **Dev container configuration** list on the advanced creation page; the GitHub CLI prompts for one, or takes `--devcontainer-path` on `gh codespace create`. - Each codespace is built from **exactly one** file. Settings are **not imported or inherited** between files, so shared settings must be repeated in each. - Files a configuration depends on (its Dockerfile, its setup scripts) should be **co-located** in the same subfolder. - Different branches can carry different configurations, because the file is read from the branch the codespace is created on. ## A minimal configuration The smallest useful file names a base and nothing else; every other property is optional: ```json { "name": "acme-web", "image": "ghcr.io/acme/web-dev:2026-10" } ``` From there a team adds features for extra tools, lifecycle commands for setup and editor customizations. `name` is only the label shown in the UI; it plays no part in which file a codespace uses. ## When there is no configuration If a repository has no `devcontainer.json`, or its configuration does not say which base image to use, Codespaces uses its **default dev container configuration**. That default is a Linux image carrying recent or long-term-support runtimes for many popular languages, data-science tools, and everyday utilities such as Git, the GitHub CLI and an SSH client. Running `devcontainer-info content-url` inside such a codespace prints a link to the full list of what it contains. The default is a reasonable start for a small project, but it is broad rather than exact: it carries tools the project never uses and may lack the specific version the project pins. Teams that need a reproducible environment commit their own configuration, so that a codespace created next month carries the same versions as one created today. ## Applying a change to an existing codespace A committed change affects **new** codespaces. An existing codespace keeps the container it was built with until you rebuild: 1. Pull the change into the codespace (or edit the file there). 2. Run **Codespaces: Rebuild Container** from the VS Code Command Palette, or `gh codespace rebuild` from a terminal; `--full` discards cached images and builds from freshly pulled ones. 3. If the new configuration breaks the container, the codespace opens in **recovery mode**; read the creation log, fix the file and rebuild again. A rebuild keeps everything under `/workspaces`, which includes the clone of the repository and uncommitted edits. Changes made elsewhere in the container, such as a tool installed by hand, survive a stop and start but are cleared by a rebuild, which is exactly why anything the team needs belongs in the configuration rather than in someone's terminal history. ## Customization, not personalization The file is shared, so it should hold what every contributor needs: runtimes, linters, required extensions, setup commands. Personal choices such as a colour theme or shell aliases belong in each person's own settings, which Codespaces applies separately, not in the repository's configuration.

  • How do you create a codespace from one of several configurations without using the web UI?
    With the GitHub CLI, run `gh codespace create` and pass `--devcontainer-path .devcontainer/api/devcontainer.json` to name the file. Without the flag, when the branch has more than one configuration, the CLI lists the paths it found and prompts you to pick one, just as the web UI's advanced creation page offers a choice.
  • What survives a container rebuild in a codespace, and what is lost?
    Everything under `/workspaces` survives: the repository clone, uncommitted edits and anything else stored there. Changes elsewhere in the container, such as packages installed by hand or edits to `~/.bashrc`, survive a stop and start but are cleared by a rebuild. Put team tooling in the configuration, or symlink files kept under `/workspaces` from a lifecycle command.

  • A file named devcontainer.json at the repository root, without the leading period, is picked up
  • A subfolder configuration inherits the settings of the main devcontainer.json
  • Without a devcontainer.json the repository cannot have codespaces at all
  • Committing a configuration change rebuilds every existing codespace automatically
  • Tools installed by hand outside /workspaces survive a container rebuild
open as a page

In a GitHub Codespaces devcontainer.json, in what order do the lifecycle commands run, and which should install the project's dependencies?

level: middleimportance: must knowfreq 33%

basics

~10 s

onCreateCommand, updateContentCommand and postCreateCommand finish setup once; postStartCommand runs at every start and postAttachCommand at every attach. Source-dependent installs belong in updateContentCommand, which the editor waits for by default.

open as a page

In a GitHub Codespaces devcontainer.json, which properties give new contributors the team's extensions, a big enough machine and a prompt for their API key?

level: middleimportance: should knowfreq 16%

basics

~10 s

customizations.vscode sets extensions and editor settings, hostRequirements hides machine types below a minimum, and a top-level secrets object prompts creators for recommended personal secrets; customizations.codespaces adds openFiles and extra repository permissions.

open as a page

In a GitHub Codespaces devcontainer.json, what are dev container features, and how do they differ from installing tools in a lifecycle command?

level: middleimportance: should knowfreq 30%

basics

~20 s

Features are versioned, shareable install units referenced by ID in the features object. Their scripts run as root during the image build, each as a cached layer, whereas lifecycle commands run later inside the started container.

open as a page

In a GitHub Codespaces devcontainer.json, when do you use image, build.dockerfile, or dockerComposeFile with service for a front end, API and database?

level: middleimportance: should knowfreq 26%

basics

~20 s

Use image to start from a ready-made image, build.dockerfile when the repository must extend it, and dockerComposeFile with service when the environment needs several containers, such as a separate database, with the editor attached to one.

open as a page

In GitHub Codespaces, a prebuild is ready yet new codespaces still spend minutes on setup: which devcontainer.json commands does a prebuild run, and which never?

level: seniorimportance: should knowfreq 21%

basics

~10 s

A prebuild runs setup up to and including onCreateCommand and updateContentCommand in a temporary codespace, then snapshots it; postCreateCommand never runs there. Slow work left in postCreateCommand therefore still runs at every creation.

open as a page