Configure VS Code Remote - Containers for Consistent Docker‑Based Development

Quick answer

To develop inside a Docker container with VS Code, add a .devcontainer/devcontainer.json file to your project root and use the Remote - Containers extension to open the folder in a container. This gives you an isolated environment that matches your production dependencies.

Worked configuration

Create the file .devcontainer/devcontainer.json with the following minimal example:

{
  "name": "My Project Container",
  "image": "mcr.microsoft.com/vscode/devcontainers/python:3.11",
  "forwardPorts": [8000],
  "postCreateCommand": "pip install -r requirements.txt",
  "extensions": [
    "ms-python.python"
  ]
}

Place this file, then in VS Code:

1. Open the folder containing the devcontainer.
2. Press Ctrl+Shift+P (or Cmd+Shift+P on macOS) and run Remote-Containers: Open Folder in Container.
3. VS Code will build or pull the image, start a container, mount the workspace, and attach.

You must run these steps on a host where the Docker daemon is accessible and your user belongs to the docker group (or you run VS Code with sufficient privileges). No additional configuration is needed if Docker Desktop is running.

Verification

• Check the lower‑left status bar; it should show Dev Container: mcr.microsoft.com/vscode/devcontainers/python:3.11.
• Open a terminal inside VS Code and run docker ps. You should see a container based on the image you specified.
• Run ls /workspace (or the path you mounted) to confirm your project files are present.
• Open the Extensions view; extensions listed in extensions appear with a (Dev Container) tag.

Limits and common mistakes

• Startup time: The first launch may take tens of seconds to pull the image and start the container. Subsequent starts are faster if the image is cached.
• Docker requirement: You need Docker Engine version 20.10 or later (Docker Desktop on macOS/Windows or a Linux daemon). Without a running daemon VS Code cannot attach.
• Extension compatibility: Some extensions that rely on native host binaries may not work fully inside the container. Test critical extensions after attaching.
• File‑system performance: Large workspaces can feel slow because of the bind‑mount. Use the workspaceMount option or add a .devcontainer/docker-compose.yml with cached or delegated mount flags to improve speed.
• Privileged ports: Forwarding ports below 1024 requires the container to have the NET_BIND_SERVICE capability or host‑side privileges; otherwise the port will not be reachable.
• Common mistakes:
  • Editing devcontainer.json and forgetting to reload the window (Remote-Containers: Reopen Folder in Container) – changes won’t take effect.
  • Using a base image that lacks the shells or tools VS Code expects (e.g., no bash in the image) leading to attachment failures.
  • Running VS Code as a regular user without Docker socket access; you’ll see an error like “Cannot connect to the Docker daemon”. Ensure your user is in the docker group or start VS Code with sudo (not recommended).