In GitHub Codespaces, where can a repository's devcontainer.json live, and what does a codespace use when there is none?
answer
- a hidden folder at the root
- leading period when at the root
- one subfolder per alternative
- nothing inherited between files
- a default image full of runtimes
basics
~10 sCodespaces 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 sThe 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
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.
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.
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.
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