|
| 1 | +--- |
| 2 | +title: Set up Dev Containers on Windows |
| 3 | +description: Learn how to set up Dev Containers on Windows using Docker Desktop and WSL 2, including the key file system placement requirement for good performance. |
| 4 | +ms.topic: install-set-up-deploy |
| 5 | +ms.date: 04/15/2026 |
| 6 | +--- |
| 7 | + |
| 8 | +# Set up Dev Containers on Windows |
| 9 | + |
| 10 | +A Dev Container lets you use a Docker container as a full development environment, defined by a `devcontainer.json` file checked into your repository. Everyone who opens the project gets the same tools, extensions, and settings — regardless of what's installed on their local machine. |
| 11 | + |
| 12 | +This page covers the Windows-specific setup. For a full introduction to what Dev Containers are and how they work, see [Dev Containers documentation](https://code.visualstudio.com/docs/devcontainers/containers) on the VS Code website. |
| 13 | + |
| 14 | +## Prerequisites |
| 15 | + |
| 16 | +Dev Containers on Windows requires: |
| 17 | + |
| 18 | +- **WSL 2** — Windows Subsystem for Linux, version 2. [Install WSL](/windows/wsl/install) if you haven't already. |
| 19 | +- **Docker Desktop for Windows** with the WSL 2 backend enabled. [Download Docker Desktop](https://www.docker.com/products/docker-desktop/) and follow the installer. During setup, ensure **Use WSL 2 based engine** is selected in Docker Desktop settings (**Settings** > **General**). |
| 20 | +- **Visual Studio Code** — [Download VS Code](https://code.visualstudio.com/). |
| 21 | +- **Dev Containers extension** — Install the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) from the VS Code Marketplace. |
| 22 | + |
| 23 | +## Where you store your files matters |
| 24 | + |
| 25 | +> [!IMPORTANT] |
| 26 | +> On Windows, Dev Container performance depends heavily on where your project files live. Store your project in the **WSL 2 file system** (for example, `/home/yourname/projects/`), not in the Windows file system (for example, `C:\Users\yourname\projects\`). |
| 27 | +
|
| 28 | +When your files are on the Windows file system (`C:\`), Docker accesses them through a cross-OS file share, which is significantly slower. When your files are in the WSL 2 file system, Docker uses native Linux I/O and performance is substantially better — especially for builds and file-watching tools. |
| 29 | + |
| 30 | +To clone into the WSL 2 file system, open your WSL distribution (for example, Ubuntu) from the Start menu or Windows Terminal, and clone there: |
| 31 | + |
| 32 | +```bash |
| 33 | +cd ~ |
| 34 | +mkdir projects && cd projects |
| 35 | +git clone https://github.com/your-org/your-repo.git |
| 36 | +``` |
| 37 | + |
| 38 | +Then open that folder in VS Code from WSL: |
| 39 | + |
| 40 | +```bash |
| 41 | +code your-repo |
| 42 | +``` |
| 43 | + |
| 44 | +VS Code connects to WSL and detects the `devcontainer.json` if one is present. |
| 45 | + |
| 46 | +## Open a project in a Dev Container |
| 47 | + |
| 48 | +Once your project is open in VS Code (connected to WSL): |
| 49 | + |
| 50 | +1. Press <kbd>F1</kbd> and select **Dev Containers: Reopen in Container**. |
| 51 | +2. VS Code builds the container image defined in `.devcontainer/devcontainer.json` (or prompts you to add one if none exists). |
| 52 | +3. When the build is complete, VS Code reconnects inside the container with all configured tools and extensions available. |
| 53 | + |
| 54 | +To return to your local environment, press <kbd>F1</kbd> and select **Dev Containers: Reopen Folder Locally**. |
| 55 | + |
| 56 | +## Add a Dev Container to an existing project |
| 57 | + |
| 58 | +If your project doesn't have a `devcontainer.json` yet: |
| 59 | + |
| 60 | +1. Press <kbd>F1</kbd> and select **Dev Containers: Add Dev Container Configuration Files**. |
| 61 | +2. Choose a base image (for example, Node.js, Python, or a generic Debian/Ubuntu image). |
| 62 | +3. VS Code creates a `.devcontainer/devcontainer.json` file you can check into source control. |
| 63 | + |
| 64 | +For the full reference of `devcontainer.json` options, see [devcontainer.json reference](https://containers.dev/implementors/json_reference/) on the Dev Container Specification site. |
| 65 | + |
| 66 | +## Troubleshooting |
| 67 | + |
| 68 | +**Container starts but file changes aren't detected** |
| 69 | +Your project is likely stored on the Windows file system. Move it into WSL (see [Where you store your files matters](#where-you-store-your-files-matters) above). |
| 70 | + |
| 71 | +**Docker Desktop doesn't start or WSL integration is missing** |
| 72 | +Open Docker Desktop, go to **Settings** > **Resources** > **WSL integration**, and enable integration for your installed WSL distributions. |
| 73 | + |
| 74 | +**VS Code can't connect to the container** |
| 75 | +Ensure Docker Desktop is running before opening VS Code. Check the Docker Desktop system tray icon. |
| 76 | + |
| 77 | +## Next steps |
| 78 | + |
| 79 | +- [Dev Containers documentation](https://code.visualstudio.com/docs/devcontainers/containers) — complete reference from the VS Code team |
| 80 | +- [devcontainer.json reference](https://containers.dev/implementors/json_reference/) — all configuration options |
| 81 | +- [Get started with Docker remote containers on WSL 2](/windows/wsl/tutorials/wsl-containers) — broader WSL + Docker setup guide |
| 82 | +- [Install WSL](/windows/wsl/install) — if you haven't set up WSL yet |
0 commit comments