# Dev Containers Spec: The devcontainer.json Standard for Reproducible Development Environments

> The devcontainers/spec repository defines devcontainer.json, an open specification for configuring containerized development environments that work consistently across local machines, cloud editors, and CI pipelines. The spec itself is a document repository licensed under CC-BY-4.0; the implementation tools live in separate repositories. The last change to the spec was on 2026-03-20.

**devcontainers/spec** — Development Containers: Use a container as a full-featured development environment.

- Repository: https://github.com/devcontainers/spec
- Website: https://containers.dev
- Stars: 5,739 · Forks: 500
- Language: Unknown
- License: CC-BY-4.0
- Published: 2026-09-22 · Updated: 2026-09-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/devcontainers-spec

## What Problem devcontainer.json Solves

Reproducing a development environment across machines has historically required written instructions, install scripts, or detailed READMEs that drift from reality. A developer on macOS with one set of tools and a colleague on Windows with another routinely encounter version mismatches, missing system libraries, or broken paths. CI environments add a third configuration to synchronise. devcontainer.json addresses this by encoding the entire environment specification in a structured file that a container runtime can act on. The file travels with the codebase, sits in version control, and is read by the same tooling whether a developer opens the repository locally, in a cloud editor, or in a CI run. The specification covers which container image to use, which ports to forward, which VS Code extensions to install, which post-create commands to run, and any Features (reusable capability bundles) to layer on top of the base image.

## devcontainer.json Format and Key Fields

The file format is JSONC: JSON with comments, which allows inline documentation of configuration choices. The README describes it as structured metadata that tools use to store configuration required for developing inside local or cloud-based containerised coding environments. Beyond the base image or Dockerfile reference, the format supports a `devcontainer.metadata` image label that embeds the same settings directly into a container image, so that any tool pulling that image inherits the development configuration without needing a separate file. The specification documents live in the `docs/specs` folder of the repository. Active proposals for new features are in the `proposals` folder. The schema files in the `schemas` directory define the valid structure for automated validation.

## Features: Reusable Capability Bundles

Dev Container Features are self-contained units that add tools, runtimes, or settings to a base image. They are defined separately from the core spec in the devcontainers/features repository, which contains spec-maintained Features. A Feature can install a language runtime, configure a shell, or add a system tool, and multiple Features can be combined in a single devcontainer.json. The README describes the Features system as part of how the specification enriches existing container formats with development-specific settings. For developers writing their own Features or needing features not in the official collection, the spec defines the interface that third-party Feature authors must follow, which means Features from different sources can be composed predictably.

## Using Dev Containers in CI with devcontainers/ci

One of the stated goals in the README is reusing the local development container in continuous integration. The devcontainers/ci repository provides a GitHub Action and an Azure DevOps Task built on the same devcontainer.json format. A team that already has a devcontainer.json can point the CI action at it and run builds and tests inside the same container image that developers use locally. This removes a category of failures where code passes CI but fails locally or vice versa because the two environments differ. The CLI reference implementation at devcontainers/cli is the underlying tool that both the GitHub Action and the editor integrations call; it is separate from the spec repository.

## Maintenance Status and Licence

The last push to the devcontainers/spec repository was on 2026-03-20, which is more than six months before this article. The specification has not been updated since that date based on the repository activity. Copyright is held by Microsoft Corporation, and the documentation is licensed under Creative Commons Attribution 4.0 (CC-BY-4.0). A separate `LICENSE-CODE` file covers any code samples in the repository. The CC-BY-4.0 licence requires attribution when reproducing spec content but permits commercial and non-commercial use. Contributions to the spec are handled through GitHub issues and pull requests as described in `CONTRIBUTING.md`.

## Limitations: Spec vs. Implementation, and Platform Scope

The devcontainers/spec repository is a specification, not an executable tool. Cloning it gives access to the documents and schemas but not a runnable environment. All executable tooling lives in other repositories: devcontainers/cli for the command-line implementation, devcontainers/features and devcontainers/templates for the officially maintained Feature and template libraries, and devcontainers/ci for the GitHub Action and Azure DevOps Task. A developer who wants to create or open a Dev Container must use one of those tools or an editor that integrates them, such as VS Code or GitHub Codespaces. The spec also does not cover Windows containers: the README describes Dev Containers as working with Docker, which supports Linux containers on Windows via WSL2 but does not define a Windows-container variant.

## Comparison to Docker Compose Alone

Docker Compose defines services, networks, and volumes for multi-container applications. A devcontainer.json can reference a Docker Compose file to take advantage of that orchestration, but the Dev Containers spec adds a layer that Docker Compose does not provide: development-specific configuration such as editor extensions, forwarded ports for local access, post-create scripts for installing development tools, and the Features system for composable capability bundles. A team using only Docker Compose gets a reproducible runtime environment; Dev Containers adds the tooling layer that turns that runtime into a complete development setup. The spec also defines what a compliant tool must do with each field, whereas Docker Compose has no mechanism for specifying editor settings or development-time post-create hooks. A devcontainer.json can reference a Docker Compose file, combining the orchestration that Compose provides with the developer tooling layer that the Dev Containers spec defines.

## Conclusion

Developers who want consistent, shareable development environments across their team should read this specification and then use the CLI at devcontainers/cli or a supporting editor like VS Code to act on it. The spec is the right starting point for understanding what devcontainer.json fields are authoritative versus editor-specific extensions. Teams considering Dev Containers only for CI should look at devcontainers/ci, which provides a GitHub Action and Azure DevOps Task backed by the same spec. The spec repository itself is not where you file feature requests for the CLI or for VS Code; those go to devcontainers/cli and devcontainers/features respectively. The CC-BY-4.0 licence on the spec documents means anyone can reproduce or build on the spec text with attribution, but the code tools in other devcontainers repositories have their own separate licences that must be checked individually.

## FAQ

### What are Dev container features?

Dev Container Features are self-contained bundles that add tools, runtimes, or shell configurations to a base container image. They are composable: multiple Features can be listed in a devcontainer.json and the tooling applies them in order. The official Feature collection is maintained in the devcontainers/features repository.

### Can I use Dev Containers on Windows?

Yes. The Dev Containers tooling runs on Windows using Docker with WSL2 for Linux container support. The devcontainers/spec README does not define a Windows-container variant; the containers themselves run Linux images.

### What are the key differences between Dev Containers and Docker Containers?

A Docker container is a runtime environment. A Dev Container adds a layer of development-specific configuration on top: editor extensions, post-create setup scripts, port forwarding rules, and the Features system. The devcontainer.json file is the structured format that records those additions.

## Sources

- [devcontainers/spec on GitHub](https://github.com/devcontainers/spec)
- [Issues](https://github.com/devcontainers/spec/issues)
- [License: CC-BY-4.0](https://github.com/devcontainers/spec/blob/main/LICENSE)
- [Project website](https://containers.dev)
- [README](https://github.com/devcontainers/spec/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/devcontainers-spec