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 basics and advanced operations.
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.
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.

​
Docker basics

​
Core concepts

A read-only template with the code, runtime, libraries, and config needed to run an app. Think of it as an install disc.
Common docker run options: container name (--name), port mapping (-p host:container), volume mount (-v host-dir:container-dir, for persistence), environment variables (-e, e.g. connection info, API keys).

​
Common commands

CommandPurposeExample
docker runStart a containerdocker run -it --name my_ubuntu ubuntu bash
docker buildBuild an imagedocker build -t my-image .
docker psList running containers (-a includes stopped)docker ps -a
docker imagesList all imagesdocker images
docker stopStop a containerdocker stop my_container
docker rmRemove a containerdocker rm my_container
docker rmiRemove an imagedocker rmi my-image
docker execRun a command in a running containerdocker exec -it my_container bash
docker restartRestart a containerdocker restart my_container
docker update --restart=alwaysAuto-restart on bootdocker update --restart=always my_container
docker <COMMAND> --helpShow help for a commanddocker run --help

​
Build an image and run a container

1

Create a Dockerfile

FROM ubuntu:latest
RUN apt-get update && apt-get install -y python3
CMD ["python3", "-c", "print('Hello, world!')"]
2

Build the image

docker build -t my-python-image .
3

Run the container

docker run my-python-image

​
Advanced techniques

  • Custom images: use a Dockerfile to define the base image, copy files, and install specific software versions and dependencies.
  • Persist data with Volumes: Docker Volumes persist container data to the host or external storage, so data survives container deletion.
  • Networking: Docker offers bridge / host / overlay network modes to control inter-container communication and outbound connectivity.
  • Docker Hub: Docker’s cloud image registry; pull others’ images and push your own to share.