Skip to content
Tutorials Center
My learning

Topics

Lesson 33 of 40 ยท Git and Remote Development

Dev Containers

Set up a reproducible development environment with VS Code Dev Containers: devcontainer.json, images, features, extensions, forwarded ports and lifecycle commands.

"It works on my machine" is an old joke with a real cause: every developer's computer has different tool versions. A dev container fixes that by describing the development environment as code. The project says which image to use, which tools to add and which extensions to install; VS Code starts a container from that recipe and opens your folder inside it. A new teammate clones the repository, clicks one button and has the exact same compiler, runtime and settings as everyone else.

This lesson explains the file, the common properties and the workflow. You need Docker (or a compatible container engine) and the Dev Containers extension to use it for real; we cannot run containers on this site, so the examples are described, and the runnable stand-ins validate and merge configuration in JavaScript.

The workflow

  1. Install Docker and the Dev Containers extension (ms-vscode-remote.remote-containers).
  2. Open your project folder.
  3. Run Dev Containers: Add Dev Container Configuration Files... and pick a template, such as a Node or Python image.
  4. Run Dev Containers: Reopen in Container. VS Code builds or pulls the image, starts the container, mounts your folder and reconnects the window.

The bottom-left corner now reads Dev Container: .... Everything that applies to remote development applies here: a server runs in the container, the terminal is a shell inside it, and workspace extensions install inside it.

Your source code stays on your disk and is mounted into the container, so changes persist even if you delete the container. Installed packages live in the container, so they disappear when it is rebuilt unless you put them in a volume.

flowchart LR
    R["Repo with .devcontainer/devcontainer.json"] --> B["Build or pull image"]
    B --> C["Start container + mount folder"]
    C --> V["VS Code connects"]

From repository to a ready environment.

devcontainer.json

The file lives at .devcontainer/devcontainer.json (or .devcontainer.json at the root). It is JSON with comments allowed.

JSON
{
  "name": "Node 22 app",
  "image": "mcr.microsoft.com/devcontainers/javascript-node:22",
  "features": {
    "ghcr.io/devcontainers/features/git:1": {}
  },
  "forwardPorts": [3000],
  "postCreateCommand": "npm install",
  "customizations": {
    "vscode": {
      "extensions": ["esbenp.prettier-vscode", "dbaeumer.vscode-eslint"],
      "settings": { "editor.formatOnSave": true }
    }
  },
  "remoteUser": "node"
}
Property Meaning
name Display name
image A ready-made image to use
build Build from a Dockerfile: { "dockerfile": "Dockerfile", "context": ".." }
dockerComposeFile and service Use a Compose setup, for example an app plus a database
features Add tools to the image from the Features registry (Git, Node, Docker CLI, ...)
forwardPorts Ports to forward to your machine
postCreateCommand Runs once after the container is created
postStartCommand, postAttachCommand Run on start or each attach
customizations.vscode.extensions Extensions installed in the container
customizations.vscode.settings Default settings for this container
containerEnv, remoteEnv Environment variables
mounts Extra bind mounts or volumes
remoteUser User the tools run as (avoid running everything as root)

Choose either image, build or dockerComposeFile, not several.

A Dockerfile-based setup

JSON
{
  "name": "Python data project",
  "build": { "dockerfile": "Dockerfile" },
  "postCreateCommand": "pip install -r requirements.txt",
  "customizations": { "vscode": { "extensions": ["ms-python.python"] } }
}

with a small Dockerfile next to it that starts FROM an official Python image and installs system packages.

Features

Features are reusable installers. Instead of writing apt-get lines for Git, the GitHub CLI or a Node version, you list them under features with options. They keep the Dockerfile short and consistent.

Why teams like them

  • Reproducible: the same tool versions for everyone and for CI.
  • Fast onboarding: one command instead of a two-page setup document.
  • Isolated: the project's dependencies do not touch your machine.
  • Disposable: break the environment, rebuild it with Dev Containers: Rebuild Container.

Costs and pitfalls

  • Docker must run, and images take disk space.
  • File access across a bind mount can be slow on some systems; use a named volume for heavy folders such as node_modules.
  • Secrets must not be baked into the image or committed in devcontainer.json; pass them with environment variables from outside.
  • Rebuild after changing the config, otherwise the old environment stays.
  • Git credentials and SSH keys are shared into the container through the editor's forwarding, not by copying private keys.

Runnable stand-ins

JS Stand-in: validate a devcontainer config

Press Run (or Ctrl + Enter) to see the console output here.

No output.

JS Stand-in: merge settings from layers

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Where is the dev container configuration stored?

    The configuration lives in .devcontainer/devcontainer.json or .devcontainer.json at the repository root.
  2. 2. What does postCreateCommand do?

    postCreateCommand runs after creation; it is the usual place to install dependencies.
  3. 3. Where do your source files live when you use a dev container?

    The folder is bind-mounted, so your files survive container deletion.
  4. 4. Which is the safe way to handle a secret API key?

    Secrets should never be committed or baked into images; supply them at runtime from your environment.

Summary

  • A dev container describes a development environment as code, using devcontainer.json.
  • Choose image, build or dockerComposeFile; add tools with features.
  • customizations.vscode.extensions installs extensions inside the container.
  • Lifecycle commands such as postCreateCommand automate setup.
  • Keep secrets out of the repository and image, and use volumes for heavy folders.

Next: Keyboard Shortcuts and Keybindings