Docker Desktop and WSL2: Taming the Ever-Growing VHDX

Where the gigabytes actually hide

Docker Desktop on WSL2 keeps everything — images, containers, volumes, build cache — in special WSL distros, each stored as a single dynamic VHDX file on C:. Every pull adds layers, every build adds cache, and deleting any of it only frees space inside the Linux filesystem: the host file stays at its high-water mark. Your own Ubuntu or Debian distro plays the same trick with its own ext4.vhdx, and none of this shows up in a "biggest folders" hunt, because to Windows it's all a few opaque files.

• docker-desktop-data (older Docker) or docker_data.vhdx (newer): the main 30–80 GB culprit under %LOCALAPPDATA%\Docker\wsl — images, containers, volumes, build cache
• docker-desktop: the smaller system distro that runs the Docker engine itself
• Your own WSL2 distros: one ext4.vhdx each under %LOCALAPPDATA%\Packages\...\LocalState
• Build cache: docker builder keeps intermediate layers even after you delete the final image
• Dangling images and stopped containers: orphaned layers from interrupted builds and pulls
• Anonymous volumes: created quietly per build by compose files, surviving even docker image prune

Clean inside first — shrinking a dirty disk is wasted work

Compacting a VHDX still full of dead images just produces a smaller file that grows right back, so the order of operations matters. Start inside: docker system df shows what images, containers, volumes and cache actually hold, and the numbers are usually a surprise. docker system prune -a removes unused images and stopped containers, --volumes adds orphaned volumes — make sure you're not deleting database data you actually wanted. docker builder prune then clears the build cache that repeated rebuilds love to bloat; only when docker system df reports a number you accept is it worth touching the host file.

Then shrink the disk: three supported ways

Run wsl --shutdown first, or the file is locked by running containers and distros. On recent WSL builds, wsl --manage <distro> --set-sparse true marks the VHDX sparse so Windows can reclaim free blocks; on older setups the reliable route is export and import — wsl --export to a .tar, wsl --unregister, wsl --import into a fresh folder — which rebuilds the file at the real data size. Docker Desktop can also move the whole disk image to another drive under Settings > Resources > Advanced, and it migrates the data for you — the honest fix when C: is simply too small for your work. And cap the growth while you're there: the same settings page has a disk-size limit, and a monthly docker system df habit keeps you under it.

Questions and Answers

Read next