Skip to main content
Docker WSL 2 Windows Docker is an open-source application container engine that packages an app with its dependencies into a portable container that runs anywhere supported. Containers are sandboxed and isolated from each other with very low overhead. This note runs Docker on Windows on top of WSL 2, from WSL setup through Docker installed and running for the first time. For commands, configuration, and Compose once it is installed, see Docker Commands, Configuration, and Compose; to build your own image, see How to Write a Dockerfile.
Windows Pro or Enterprise is recommended: they include Hyper-V and full virtualization, giving the most complete Docker Desktop experience with the fewest setup pitfalls. Windows Home can still run Docker via the WSL 2 backend but lacks Hyper-V and some features, which is more limiting for advanced virtualization needs.

​
Installing WSL

WSL (Windows Subsystem for Linux) runs a Linux environment on Windows and is the best foundation for Docker on Windows.
The modern wsl --install automatically enables the required Windows features and installs the default distro, so manual feature toggling is usually unnecessary. The manual step 1 below is for fine-grained control or when auto-install fails. WSL 2 only needs “Virtual Machine Platform” and “Windows Subsystem for Linux”; Hyper-V and Windows Hypervisor Platform are not required (and Hyper-V is absent on Windows Home).
1

Enable features (optional, if auto-install fails)

Control Panel → Programs → Turn Windows features on or off, check:
  • Virtual Machine Platform (required)
  • Windows Subsystem for Linux (required)
  • Hyper-V, Windows Hypervisor Platform (optional, not required for WSL 2)
Click OK and restart.
2

Install WSL

Open PowerShell or Command Prompt as administrator and run:
wsl --update
wsl --install
This enables the required features and installs the default Linux distro (Ubuntu). Restart afterwards.
3

Set up the Linux user

On first launch the new distro opens a console, waits for files to extract (faster afterwards), and prompts you to create a username and password.
4

Verify WSL

Check the WSL version and installed distros:
wsl -l -v
5

Set WSL 2 as default

WSL 2 is the recommended environment for Docker:
wsl --set-default-version 2
6

Change the default distro (optional)

List available distros and install a specific one with -d:
wsl --list --online
wsl --install -d <distro-name>
7

Start as root (if no user was set in step 3)

If wsl --install did not prompt for a username/password, enter as root first, then create an account manually:
wsl.exe --user root
8

Tune WSL 2 resources (optional)

Edit C:\Users\<your-username>\.wslconfig to cap WSL 2 memory and processors. The [wsl2] section header is mandatory, or the settings are ignored:
[wsl2]
memory=8GB      # WSL 2 VM memory cap
processors=16   # virtual processors for the WSL 2 VM
swap=8GB        # swap size
Apply with wsl --shutdown to restart WSL. Docker’s CPU and memory on the WSL 2 backend are controlled by this file (not the Docker Desktop GUI); see Performance settings.
9

Integrate VS Code and Windows Terminal (optional)

VS Code integrates with WSL automatically once installed, so you can edit and compile inside WSL. Windows Terminal lets you switch between multiple Linux terminals and PowerShell.

​
Installing Docker

Use Docker Desktop with the WSL 2 engine on Windows.
1

Install Docker Desktop

Download the installer from Docker and follow the prompts; mind the system requirements.
2

Launch Docker Desktop

Start it from the Windows Start menu after installation.
3

Enable the WSL 2 engine and integration

Settings (top-right gear) → General, check “Use the WSL 2 based engine”; Resources → WSL Integration, select the distros to enable Docker integration for, then Apply & Restart.
4

Verify Docker

In the WSL Linux terminal run:
docker run hello-world
docker version
Run the verification in the WSL terminal; on success you should see output like this:
Docker Desktop requires a paid subscription for large enterprises (above the official employee or revenue thresholds); personal and small-team use is free. See Docker’s licensing terms.

​
Next steps

Once installed, continue here. Usage and configuration: Dockerfile (build your own image):