Setting Up a Development Environment with VS Code Dev Containers on Windows

Introduction

It might seem a bit late to cover this given the title, but I’ve put this article together to organize my own knowledge ☕
The other day, while making my first post, I took a look at many other contributions and was often amazed, thinking, "Everyone's level is so high..."
However, rather than feeling discouraged, it makes me feel positive—like "I should keep studying little by little too."

What led me to write this article

Among the many technologies being discussed, the presence of Claude Code left a particularly strong impression on me.
"I've heard the name, but what exactly is Claude Code?"
Being quite uninformed, I immediately bought the following book:
https://gihyo.jp/book/2026/978-4-297-15354-0
The book has been very educational. In it, there was a section about using VS Code's Dev Containers to create a container.
My PC's OS is Windows. I got confused thinking, "WSL, Docker, Ubuntu, containers... what does the setup look like now?" and decided to write this article to organize my thoughts ✏️

The goal this time 🍅

The goal of this article is to get a general understanding of the relationship between "Windows + WSL + Docker + Containers."
To that end, I will deepen our understanding by introducing the steps to create an Ubuntu instance using WSL in a Windows environment and then building a container on top of it.

It might seem like a roundabout way of doing things, but please understand that this is for the sake of learning.

Brief introduction of the technologies in this article 🗒️

Here is a brief introduction to the technologies featured in this article.

Name	Description
Windows 11	The operating system developed by Microsoft.
WSL2	Windows Subsystem for Linux 2. While WSL1 emulated the kernel, WSL2 is a lightweight VM using Hyper-V technology that runs a real Linux kernel.
Docker Desktop	A desktop application for Windows and Mac that integrates a container execution environment and a management GUI.
Visual Studio Code	A lightweight, high-performance OSS editor with rich extensions and debugging features. Hereafter referred to as VS Code.

Name	Description
Ubuntu	A Debian-based distribution widely used for desktop and server purposes.
docker-desktop	Manages the creation, starting, and stopping of containers as the host for the Docker Engine.
Docker Engine	The core component of Docker responsible for creating, running, and managing containers using Linux kernel features.

Name	Description
Dev Containers (VS Code extension)	Development Containers. A system to define and share containers as development environments within VS Code and other tools.
WSL (VS Code extension)	An extension that allows direct operation of the WSL environment from VS Code.

Actual Construction

1. Install Docker Desktop

The method for installing Docker Desktop on Windows can be found quickly by searching, so I will omit it here.
I recall there used to be a step to manually install WSL2 until recently, but it seems it is now set up automatically.

Once completed, you should see a 🐧 in your File Explorer as shown in the image.

I believe Ubuntu was installed at the same time, but if it's missing, you can install it via command line (wsl --install -d Ubuntu).
At this stage, the relationship diagram between Windows, WSL2, and Docker is as follows:

The role of the docker-desktop distribution is to manage the creation, starting, and stopping of containers as the host for the Docker Engine.

Previously, docker-desktop-data existed, but it has been discontinued in updates starting from Docker Desktop 4.30. Instead, it seems to create and manage its own virtual hard disk (VHDX) for storage.
Reference: https://docs.docker.com/desktop/features/wsl/best-practices/

This time, I want to create a container from Ubuntu within WSL.

2. Install the "Dev Containers" and "WSL" extensions in Visual Studio Code

Open VS Code and perform the following:

1. Open the Extensions view from the left menu and install "Dev Containers."
   → This is a system to define and share containers as development environments within VS Code and other tools.
2. Install the "WSL" extension.
   → This allows you to operate the WSL environment directly from VS Code.

3. Click the icon that looks like "><" in the bottom left of Visual Studio Code to connect to WSL

Preparation is complete to connect from the host (Windows 11) VS Code to Ubuntu on WSL.
Next, I'll explain how to connect.

1. You should see an icon like >< in the bottom left of VS Code, so click it.
   
2. A menu will then appear at the top, showing "Connect to WSL."
   
3. Click it to connect to the Ubuntu running on WSL.
   

Since VS Code is now connected to Ubuntu:

You are in a state where you are connected to the Ubuntu highlighted in the red frame below.

I have added VS Code and the WSL extension to the previous diagram.
You are remotely connecting to Ubuntu by following the red line.

4. Create definition files to build the container

Control the Docker Engine from Ubuntu to create the container.
When creating the container, use VS Code's Dev Containers to build it.
The directory structure will be as follows:

project/
└── .devcontainer/
    ├── devcontainer.json
    └── Dockerfile

You can create these files either on Ubuntu or Windows.
I created mine on Windows. I was careful to save the files with LF line endings.

Prepare the devcontainer.json and Dockerfile.
Since this is just a sample, I have only defined the bare minimum; add more definitions as needed.

devcontainer.json

{
    "name": "My Dev Container",
    "build": {
        "dockerfile": "Dockerfile"
    },
    "customizations": {
        "vscode": {
            "extensions": []
        }
    },
    "remoteUser": "vscode"
}

A brief explanation of devcontainer.json:

Key	Description
name	The name displayed in the VS Code status bar.
build.dockerfile	The path to the Dockerfile to be used.
customizations.vscode.extensions	VS Code extensions to install inside the container (currently empty).
remoteUser	Specifies the user created in the Dockerfile.

Dockerfile

FROM ubuntu:22.04

# Timezone settings (to avoid interactive prompts)
ENV DEBIAN_FRONTEND=noninteractive

RUN apt-get update && apt-get install -y \
    curl \
    git \
    && apt-get clean \
    && rm -rf /var/lib/apt/lists/*

# Create a non-root user (recommended by VS Code)
ARG USERNAME=vscode
ARG USER_UID=1000
ARG USER_GID=$USER_UID

RUN groupadd --gid $USER_GID $USERNAME \
    && useradd --uid $USER_UID --gid $USER_GID -m $USERNAME

USER $USERNAME

A brief explanation of the Dockerfile:

Statement	Reason
FROM ubuntu:22.04	Base image (a minimal starting point).
DEBIAN_FRONTEND=noninteractive	Avoids interactive prompts during apt-get execution.
curl, git	Minimal tools often essential for development.
Non-root user creation	The user VS Code uses to operate inside the container. Using root often leads to permission issues.

If you created the above files in a Windows environment, move them to Ubuntu.
I moved the files using File Explorer.

5. Run code ./project in the Ubuntu terminal

Open the terminal in VS Code using Ctrl + Shift + @, change to bash, and then execute code ./project.
If you have already moved into the project folder, simply execute code ..

6. Create the container using the VS Code Dev Containers extension

Now, let's actually create the container.
We will use the VS Code Dev Containers extension to create the container.
This feature has the advantage of allowing anyone to instantly reproduce the same environment by describing the necessary OS, tools, and VS Code extensions in devcontainer.json.
Furthermore, as described later, it allows debugging and terminal operations with the exact same feel as a local editor via the "VS Code Server" running inside the container.

Executing the command from step 5 will open a new VS Code window.
Press Ctrl + Shift + P and select Dev Containers: Reopen in Container.

After waiting a while, you can confirm in Docker Desktop that the container has been created.

Success is indicated when My Dev Container is displayed in the search bar at the top of VS Code.
At this point, VS Code is operating (opening) the container.

Alternatively, when the window opens, a dialog like the one in the image below may appear in the bottom right, so you can also create the container from there.

At this stage, the configuration diagram is as follows:

The container is created in the order of ① to ⑤ in the diagram.
VS Code Server is a VS Code extension that runs in remote environments or inside containers.
While the VS Code on Windows handles UI rendering and key inputs, the VS Code Server takes care of actual processing such as reading/writing files, running extensions, debugging, and terminal operations.
This allows users to develop within the container or WSL environment while using the VS Code UI on Windows exactly as it is.

Summary 🏹

This time, I tried creating a container using VS Code in a Windows environment and connecting to it. (I didn't even know Docker Engine existed until I studied this! 🤷‍♂️)
If there are any errors in the content, I would appreciate your corrections.
I organized the information using as many diagrams and images as possible.
While this might be old news for some, I hope this article helps with your development.

Future Plans 🍀

The content of this article ended up deviating slightly from the main theme of the book I purchased.
Also, much of the information introduced here can likely be found in other books or websites.
I wrote this primarily to organize my own knowledge.

However, to be honest, with the advancement of AI, I sometimes wonder, "Will this knowledge be necessary in the future? Do I really need to understand this?"
My frank feeling is that AI is evolving so rapidly that it's becoming hard to keep up.
I feel it might be important not just to study and deeply understand AI, but also to think about how we should face it.

I still want to write more articles, such as continuations of previous ones, so I'll keep doing my best! 🔥