Develop Inside a Docker Container Using VS Code Remote - Containers

Desired outcome

Run, edit, and debug source code inside a consistent Linux environment provided by a Docker image, eliminating local setup differences.

Prerequisites

• Docker Engine installed and running (Docker Desktop on macOS/Windows or Docker Engine on Linux). Your user must be able to run containers without sudo.
• VS Code version 1.60 or newer.
• Remote - Containers extension installed from the VS Code Marketplace.
• A folder you want to work in that contains either a Dockerfile or a .devcontainer/devcontainer.json file describing the container.

Procedure

1. Open the folder in VS Code. From the host terminal, navigate to your project and start VS Code:

   cd /path/to/workspace-folder
   code .

   You need read access to the folder; no special permissions are required.

2. Launch the container. Press F1, type Remote-Containers: Open Folder in Container, and select the configuration.

   If you have a .devcontainer/devcontainer.json file, the extension will read it; otherwise it will look for a Dockerfile at the repository root.

3. Wait for the build and attach. The status bar shows a progress indicator. The first time may take several minutes as Docker pulls the base image and builds layers. Subsequent starts reuse cached layers.

4. Work inside the container. Once attached, the bottom-left corner displays a container name (for example, dev-container-abc123). The integrated terminal opens a shell inside the container, and you can run commands as if you were locally.

   Example: verify Node.js version

   node -v

   Expected output matches the version defined in the devcontainer image (for example, v18.17.0).

Expected checks

• Look at the VS Code status bar: a small container icon and the text Dev Container: workspace-folder confirms attachment.

• In a host terminal, run:

  docker ps --filter "name=workspace-folder" --format "{{.Names}}\t{{.Status}}"

  You should see a container whose name includes the workspace folder and a status of Up ....

• Inside the VS Code terminal, execute a language-specific tool (for example, python --version or dotnet --info) and verify the output matches the version specified in devcontainer.json.

• Make a small edit to a source file, save it, and run cat file-path in the terminal to confirm the change persists inside the container.

Troubleshooting and recovery options

Container fails to start

• Check Docker daemon logs: docker info (host) or journalctl -u docker.service (Linux).
• Ensure the user is in the docker group (Linux) or has Docker Desktop privileges (macOS/Windows). Without this, the attach step will fail with a permission error.
• If the build stalls due to large volume mounts, add a mounts section to devcontainer.json to exclude unnecessary directories, for example:

  {
    "mounts": [
      "source=${localWorkspaceFolder}/node_modules,target=/workspace/node_modules,type=bind,consistency=cached"
    ]
  }

Slow startup

• Enable Docker's cached mount feature (requires Docker Desktop 2.3+). Add cached to the consistency option as shown above.
• Prune unused images and containers periodically: docker system prune -af (host).

Reopen locally

If the container becomes unusable, you can revert to host-based work without losing code:

1. Press F1 and run Remote-Containers: Reopen Folder Locally.
2. VS Code closes the container window and reopens the same folder on the host.
3. You can later retry Remote-Containers: Open Folder in Container after fixing the issue.

Limitations

• Extensions installed inside the container are isolated from the host VS Code installation. After a container rebuild, you must reinstall needed extensions or list them in the extensions array of devcontainer.json.
• GUI applications that require host display (for example, X11) need additional configuration in devcontainer.json (for example, forwarding DISPLAY or using runArgs).
• Large monorepos may experience noticeable latency due to file-system synchronization; consider using workspaceFolder sub-folder mounts or a dev container per service.