Dev Containers — Portable Development Environment Specification

Introduction

Dev Containers is an open specification that defines how to configure containerized development environments. By placing a devcontainer.json in your repository, any developer can spin up an identical environment with the right language runtimes, tools, and extensions — eliminating setup friction and "works on my machine" problems.

What Dev Containers Does

• Defines development environments as code in a devcontainer.json file
• Supports pre-built base images and composable features for adding languages, tools, and CLIs
• Integrates with VS Code, GitHub Codespaces, DevPod, and other supporting tools
• Provides lifecycle hooks (postCreate, postStart, postAttach) for running setup scripts
• Enables multi-container setups via Docker Compose integration

Architecture Overview

The spec centers on devcontainer.json, a JSON file that declares base images, features (modular tool installers), port forwarding, environment variables, and lifecycle scripts. The Dev Container CLI reads this manifest, builds or pulls the container image, and starts a development session. Features are OCI artifacts that layer additional tools on top of any base image using a standard install mechanism.

Self-Hosting & Configuration

• Add .devcontainer/devcontainer.json to any repository to define the environment
• Use devcontainer up to start locally or let GitHub Codespaces read the config automatically
• Compose features from the registry at ghcr.io/devcontainers/features for common tools
• Customize with postCreateCommand for project-specific setup (installing deps, seeding databases)
• Pre-build images with devcontainer build for faster startup in CI and cloud environments

Key Features

• Open specification maintained by the Dev Containers community with Microsoft and GitHub
• Composable features: add Node, Python, Docker, Terraform, or 100+ tools without custom Dockerfiles
• Works across editors and platforms — not locked to any single IDE
• Lifecycle hooks for automated dependency installation and configuration
• Supports GPU passthrough and privileged containers for ML workloads

Comparison with Similar Tools

• Docker Compose — General container orchestration; Dev Containers add IDE integration and developer lifecycle hooks
• Nix/devenv — Reproducible environments without containers; Dev Containers use Docker for broader compatibility
• DevPod — Client that supports the Dev Container spec and adds backend flexibility
• Vagrant — VM-based environments; Dev Containers are lighter using containers

FAQ

Q: Do I need VS Code to use Dev Containers? A: No. The CLI works standalone, and other tools like DevPod and JetBrains Gateway support the spec.

Q: Can I use my own Docker images? A: Yes. Set the image field to any Docker image or use a Dockerfile for custom builds.

Q: How do features work? A: Features are OCI-published scripts that install tools. List them in devcontainer.json and they run during container creation.

Q: Is the spec truly open? A: Yes. The specification is developed openly on GitHub under the devcontainers organization.

Sources

• https://github.com/devcontainers/spec
• https://containers.dev/