Setting Up a Development Environment with WSL2 and Docker on Windows 11

What you'll end up with:

• A real Linux (Ubuntu) environment running inside Windows
• Docker Engine running natively inside that Linux environment
• VS Code connected to Linux so you can write code like a professional developer
• A fully isolated Python development container — your first dev environment

Before We Start: What Are We Actually Building?

Let's explain the key concepts before touching anything.

What is WSL2?

WSL2 stands for Windows Subsystem for Linux 2. It's a feature built into Windows 11 that lets you run a real Linux operating system (in our case, Ubuntu) directly inside Windows — no separate computer needed, no slow virtual machine. Think of it as a Linux computer living inside your Windows computer, sharing the same hardware but kept completely separate.

What is Docker?

Docker lets you create containers — isolated, lightweight environments where you can run software. Think of a container like a shipping container: everything the app needs is packed inside it, and when you're done, you can throw the whole container away without leaving a mess on your system.

For developers this means: if you want to try Python today and Node.js tomorrow, you spin up a container for each, use it, then delete it. Your main system stays completely clean.

Why install Docker inside WSL2 instead of using Docker Desktop?

Docker Desktop is a Windows application that adds a graphical interface on top of Docker. It works fine, but it runs extra background processes that use more memory and generate more heat — not ideal on a thin laptop. Installing Docker directly inside Linux (WSL2) is leaner, faster, and mirrors how Docker is used in the real world on servers. It also gives you more hands-on Linux experience.

Step 1: Install WSL2 and Ubuntu

Open PowerShell as Administrator

Click the Start menu, type PowerShell, right-click on Windows PowerShell, and select Run as administrator. A blue terminal window will open.

Run the WSL install command

wsl --install

This single command enables the WSL2 feature and installs Ubuntu (the default distribution) in one step. You may see it downloading components — let it finish.

Install Ubuntu explicitly (only if it wasn't installed automatically)

After rebooting, if Ubuntu didn't install on its own, open PowerShell as Administrator again and run:

wsl --install -d Ubuntu

This installs Ubuntu — one of the most popular Linux distributions — inside WSL2. It will download Ubuntu and then automatically open a new terminal window.

Create your Linux username and password

The Ubuntu terminal will ask you to create a username and password. This is your Linux account — separate from your Windows account.

• The username should be lowercase, no spaces (e.g., john)
• The password won't show any characters as you type — that's normal, it's a Linux security feature
• Remember these credentials, you'll need them when running commands with sudo

Confirm Ubuntu is running on WSL2

Back in PowerShell, confirm Ubuntu is running on WSL version 2 (not the older version 1):

wsl -l -v

You should see something like:

  NAME      STATE           VERSION
* Ubuntu    Stopped         2

The 2 under VERSION confirms you're on WSL2. If it shows 1, upgrade it:

wsl --set-version Ubuntu 2

If you don't see Ubuntu listed yet, it may still be installing — wait a moment and try again.

Step 2: Enable systemd in WSL2

This is a small but important step that makes everything later cleaner. systemd is the standard system-and-service manager on modern Linux — it's what starts and manages background services like Docker. Recent versions of WSL2 support it, but it isn't always switched on by default.

Enabling it now means Docker can start automatically and be managed exactly the way it would be on a real Linux server — which is both simpler and more professionally realistic than the older workarounds.

Open your Ubuntu terminal (search for "Ubuntu" in the Start menu) and create/edit the WSL config file:

sudo nano /etc/wsl.conf

Add these two lines:

[boot]
systemd=true

Save and exit nano (Ctrl+O, Enter, then Ctrl+X).

Now fully restart WSL so the change takes effect. In PowerShell (not the Ubuntu terminal):

wsl --shutdown

Wait about 10 seconds, then reopen your Ubuntu terminal. Confirm systemd is running:

systemctl is-system-running

You should see running (or possibly degraded — that's fine too; it just means one unrelated service isn't happy, not that systemd failed).

Step 3: Update Ubuntu

Before installing anything on a Linux system, it's good practice to update the list of available software and upgrade any existing packages. In your Ubuntu terminal run:

sudo apt update && sudo apt upgrade -y

This will take a minute or two. Let it finish before moving on.

Step 4: Install Docker Engine

Docker provides an official install script that handles everything automatically. Run these two commands inside your Ubuntu terminal:

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

This will take a few minutes depending on your internet connection.

Step 5: Run Docker Without sudo

By default, Docker requires administrator privileges (sudo) to run every command. To fix this, we add your user account to the docker group — a group of users who are allowed to run Docker without sudo.

sudo usermod -aG docker $USER

Apply the group change to your current session immediately:

newgrp docker

Step 6: Enable Docker to Start Automatically

Because you enabled systemd in Step 2, making Docker start on boot is now a single, standard command — the same one you'd use on any Linux server:

sudo systemctl enable --now docker

That's the entire auto-start setup. No editing shell config files, no password workarounds — systemd handles it properly.

# Auto-start Docker each time you open the terminal (fallback only)
echo 'sudo service docker start > /dev/null 2>&1' >> ~/.bashrc

# Allow starting the Docker service without a password prompt
echo "$USER ALL=(ALL) NOPASSWD: /usr/sbin/service docker start" | \
  sudo tee /etc/sudoers.d/docker-service

source ~/.bashrc

Step 7: Test Docker

Run the classic Docker test:

docker run hello-world

You should see a message that includes:

Hello from Docker!
This message shows that your installation was working correctly.

If you see that, Docker is working perfectly. Check the installed versions:

docker --version
docker compose version

To confirm the auto-start worked, fully restart WSL from PowerShell (wsl --shutdown), reopen Ubuntu, and run:

docker ps

You should see an empty table with column headers — no errors. This means Docker started automatically in the background.

Step 8: Connect VS Code to WSL2

VS Code is a free, powerful code editor made by Microsoft. It has built-in support for WSL2, which means you can open VS Code on Windows but have it edit files that live inside Linux — giving you the best of both worlds.

Install the required extensions

Open VS Code on Windows, then press Ctrl+Shift+X to open the Extensions panel. Search for and install these two extensions:

1. WSL by Microsoft (ms-vscode-remote.remote-wsl)
   • This lets VS Code connect to your WSL2 Ubuntu environment
2. Dev Containers by Microsoft (ms-vscode-remote.remote-containers)
   • This lets VS Code open and work inside Docker containers

Open your projects folder in VS Code via WSL

In your Ubuntu terminal, create a folder for your projects and open it in VS Code:

mkdir ~/projects && cd ~/projects
code .

VS Code will open a new window. Look at the bottom-left corner — you should see a green badge that says "WSL: Ubuntu". This confirms VS Code is connected to Linux.

Step 9: Create Your First Dev Container

This is where everything comes together. A Dev Container is a Docker container configured specifically for development — it has your language runtime and tools all running in isolation, and VS Code works directly inside it.

Create a test project

In your Ubuntu terminal:

mkdir ~/projects/test-app && cd ~/projects/test-app
code .

A new VS Code window opens, still showing the WSL: Ubuntu badge.

Add a Dev Container configuration

Press Ctrl+Shift+P to open the Command Palette (VS Code's search bar for commands). Type:

Dev Containers: Add Dev Container Configuration Files

Select it from the dropdown.

Choose a template

VS Code will show a list of pre-built development environments. Select Python 3.

You'll be asked a few follow-up questions:

• Python version — choose 3.12 (or the latest shown)
• Additional features — click OK without selecting anything (you can add features later)
• Optional directories — click OK to accept the defaults

VS Code will create a hidden .devcontainer/ folder in your project containing a devcontainer.json file. This file describes your container — what language it uses, which VS Code extensions to install inside it, and so on.

Open the container

In the bottom-right corner of VS Code, a popup will appear: "Reopen in Container" — click it.

If you don't see the popup, press Ctrl+Shift+P and type:

Dev Containers: Reopen in Container

VS Code will now pull the Python 3 Docker image from the internet and build your container. The first time takes a few minutes — it's downloading everything it needs. You'll see "Connecting to Dev Container" in the bottom-left.

When it's done, the bottom-left badge will change to "Dev Container: Python 3".

Verify it's working

Open the integrated terminal inside VS Code with Ctrl+` (the backtick key, usually above Tab) and run:

python --version

You should see something like Python 3.12.x.

You're Done!

Here's a summary of what you've built:

Starting a new project in the future

Every time you start a new project, the workflow is:

mkdir ~/projects/project-name && cd ~/projects/project-name
code .

Then in VS Code: Ctrl+Shift+P → Dev Containers: Add Dev Container Configuration Files → pick your language → Reopen in Container.

That's it. A fresh, isolated environment every time.

Useful Docker Commands

# See currently running containers
docker ps

# See all containers including stopped ones
docker ps -a

# See downloaded images
docker images

# Stop a running container
docker stop <container-name>

# Remove a stopped container
docker rm <container-name>

# Clean up unused images and containers (frees disk space)
docker system prune

# Check the Docker service status (systemd)
systemctl status docker

Troubleshooting