How to Set Up Docker with the WSL2 Backend

Docker Desktop’s WSL2 backend runs containers using WSL2’s own real Linux kernel rather than a separate, dedicated Hyper-V virtual machine — this walks through setting it up correctly.

Step 1: ensure WSL2 itself is installed and working

wsl --status

Confirm WSL2 (not just WSL1) is your default version before installing Docker Desktop, since the WSL2 backend specifically requires it.

Step 2: install Docker Desktop

Download Docker Desktop for Windows from Docker's
  official site and run the installer

Step 3: confirm the WSL2 backend is selected

Docker Desktop → Settings → General →
  confirm "Use the WSL 2 based engine" is checked

This should be the default on a current Docker Desktop installation, but worth confirming explicitly, especially on an upgraded older installation that might retain a prior Hyper-V-based configuration.

Step 4: enable integration for your specific distro

Docker Desktop → Settings → Resources → WSL Integration →
  toggle on for the specific distro(s) you want to
  use docker from

Integration is per-distro, not automatic for every installed distro — enable it specifically for whichever distro you actually intend to run docker commands from.

Step 5: apply the changes

Click "Apply & Restart" in Docker Desktop's settings

Step 6: verify docker works from inside the distro

docker --version
docker run hello-world

Successfully running the hello-world test container confirms the full integration path — Docker Desktop, WSL2, and your specific distro — is working correctly end to end.

Step 7: verify containers actually use the shared WSL2 kernel

uname -r

Run both inside your Docker container and inside your WSL distro directly — seeing the same kernel version confirms containers are running via WSL2’s real kernel, not a separate isolated environment.

Step 8: use Docker Compose the same way you would on native Linux

docker compose up

Once the WSL2 backend integration is working, Docker Compose and the full Docker CLI toolchain behave identically to a native Linux Docker installation — no WSL-specific command variations needed for everyday use.

Step 9: keep project files on the Linux-native filesystem for best performance

Following the general filesystem-performance guidance, keep Docker projects with bind-mounted volumes on WSL’s native filesystem rather than under /mnt/c — container builds and bind-mounted volume access both benefit meaningfully from avoiding the cross-filesystem overhead.

Why the WSL2 backend is a genuine improvement over the older Hyper-V backend

Docker Desktop’s older Hyper-V-based backend ran containers inside a separate, dedicated VM with its own resource allocation, disconnected from your regular WSL2 environment — the WSL2 backend instead shares the same underlying kernel and resource pool your regular WSL distros already use, meaning containers integrate more efficiently with files and tools already living inside your WSL environment, rather than requiring a separate, disconnected virtualization layer just for Docker specifically.

Where container storage actually lives, and why that matters for disk space

Container images, layers, volumes, and build cache managed by the WSL2 backend live inside WSL2’s own managed virtual disk, sharing the same dynamically-expanding storage behavior as any other WSL2 distro. This means the disk-space and compaction considerations covered elsewhere on this blog for WSL2’s virtual disks apply directly to Docker’s storage too — docker system prune reclaiming space inside the guest doesn’t automatically shrink the underlying .vhdx file’s on-disk size without a separate compaction step afterward.

Setting resource limits specifically for container-heavy workloads

Because Docker’s containers draw from the same shared WSL2 VM resource pool as your regular distros, a .wslconfig memory or CPU ceiling set without accounting for container workloads can starve both simultaneously under heavy use. If you run resource-intensive containers regularly, size your .wslconfig limits with that combined demand in mind, rather than tuning purely for your non-container WSL usage and being surprised when containers compete for the same capped pool.

Confirming which distro Docker commands are actually reaching

On a machine with multiple installed distros, Docker Desktop’s WSL integration can be enabled for several simultaneously, and docker commands run from each integrated distro reach the same underlying Docker daemon — not separate, per-distro daemons. Running docker context ls clarifies which context (and therefore which daemon) a given docker invocation is actually targeting, which matters if you’ve configured multiple contexts for different projects or environments.

Running Docker Engine directly inside WSL2 as an alternative to Docker Desktop

For anyone who’d rather not run Docker Desktop’s Windows-side application at all, it’s possible to install Docker Engine directly inside a systemd-enabled WSL2 distro instead, managing containers exactly as you would on bare-metal Linux — a genuinely viable path for users who want to avoid Docker Desktop’s licensing terms for certain organizational uses, at the cost of losing Docker Desktop’s own GUI and some of its cross-distro integration conveniences.

Checking Docker Desktop’s own resource settings separately from .wslconfig

Docker Desktop historically exposed its own memory and CPU sliders independent of .wslconfig, and on the WSL2 backend these two configuration surfaces can overlap or conflict if set inconsistently. Checking Docker Desktop’s own Resources settings alongside whatever .wslconfig specifies, rather than assuming only one of the two actually governs the shared VM, avoids the confusing case where a container hits a memory ceiling that doesn’t match either setting alone.

Related:

Sources: