How I Freed Docker Disk Space on Windows (WSL2 Beginner Guide)

This guide shows how to make more room on Windows when Docker Desktop uses WSL 2. It explains what is happening and gives you steps to follow.

First, what are Docker, WSL 2 and a VHDX?

Think of Docker as a workshop. It keeps tools, boxes and project files inside a big virtual backpack called a .vhdx file. WSL 2 is the small Linux computer that carries that backpack.

When you remove Docker files, the backpack can still stay the same size. The space inside is empty, but Windows may not get that space back until the backpack is compacted.

This guide has two jobs: remove Docker things you no longer need, then ask Windows to shrink the virtual disk file. It is for Docker Desktop on Windows using the WSL 2 engine.

Before you start: keep your important files safe

• These steps do not remove running containers.
• Unused images and build cache may need to be downloaded or built again. Docker will ask before removing them.
• Do not remove Docker volumes unless you know what is inside them. A volume can hold a database, photos or other important app files. This guide leaves volumes alone.
• Save work in Linux windows or terminals before stopping WSL. The shutdown step stops all WSL Linux computers on this PC.

Step 1: Look at the space you have

Open PowerShell from the Start menu. Run these commands one at a time:

Get-PSDrive -Name C | Select-Object Name,@{n='FreeGB';e={[math]::Round($_.Free/1GB,2)}}
docker system df
$vhd = Join-Path $env:LOCALAPPDATA 'Dockerwsldiskdocker_data.vhdx'
if (Test-Path -LiteralPath $vhd) { Get-Item -LiteralPath $vhd | Select-Object FullName,@{n='SizeGB';e={[math]::Round($_.Length/1GB,2)}} } else { 'The usual Docker disk file was not found.' }

The first command shows free space on C:. The second shows Docker’s images, containers, volumes and build cache. The last two look for Docker’s usual virtual disk file.

If the file was not found, stop here. Your disk may be stored elsewhere or Docker may use a different engine. In Docker Desktop, look under Settings → Resources → Advanced → Disk image location. Use the file at that location; do not guess or compact another file. See Docker’s backup and restore guide for the different disk locations.

Step 2: Remove things Docker can get again

In PowerShell, run:

docker image prune -a
docker builder prune -a

Docker will show what it plans to remove and ask you to confirm. Read the question, then type y and press Enter only if you are happy to continue. The first command removes images no container is using. Docker can download them again. The second removes saved build pieces Docker can make again.

These commands leave Docker volumes alone. See their names with docker volume ls. Do not run docker volume prune or add --volumes to a cleanup command unless you have checked that the volumes contain nothing you need.

Check Docker’s numbers again with docker system df.

Step 3: Ask Windows to shrink Docker’s virtual disk

Save your work, then quit Docker Desktop from the Docker whale menu near the clock. Open PowerShell as Administrator: open Start, type PowerShell, right-click it and choose Run as administrator. Allow the Windows prompt if you are ready.

Paste this whole block into the Administrator PowerShell window:

$vhd = Join-Path $env:LOCALAPPDATA 'Dockerwsldiskdocker_data.vhdx'
if (-not (Test-Path -LiteralPath $vhd)) {
  throw "Docker's usual disk file was not found. Stop and check Docker Desktop Settings > Resources > Advanced > Disk image location."
}
wsl --shutdown
$dp = Join-Path $env:TEMP 'docker-compact.txt'
@"
select vdisk file="$vhd"
attach vdisk readonly
compact vdisk
detach vdisk
exit
"@ | Set-Content -Path $dp -Encoding ascii
diskpart /s $dp

wsl --shutdown closes WSL so the disk is not busy. DiskPart opens the right disk as read-only and asks Windows to compact it. Read-only means this step does not change files inside the disk. Windows needs an Administrator window for this operation.

Wait for DiskPart to finish. It can take a while and may look paused. If DiskPart shows an error, do not assume it worked. Check that Docker Desktop is fully quit and that the disk path is correct. When DiskPart finishes without an error, open Docker Desktop again from Start.

Microsoft’s DiskPart instructions explain that compacting shrinks a dynamic virtual disk when it is detached or attached as read-only.

Step 4: Check whether it worked

After Docker Desktop starts, open PowerShell and run:

Get-PSDrive -Name C | Select-Object Name,@{n='FreeGB';e={[math]::Round($_.Free/1GB,2)}}
docker system df
Get-Item -LiteralPath (Join-Path $env:LOCALAPPDATA 'Dockerwsldiskdocker_data.vhdx') | Select-Object @{n='SizeGB';e={[math]::Round($_.Length/1GB,2)}}

Compare free space on C: with the number from Step 1. If Windows had kept lots of empty room inside Docker’s disk, you may now see more free space. The amount depends on how much space was empty; it may be less than in my example.

If the number barely changes, Docker may still be using the space, may have a different disk location, or may use a different engine. Check Docker Desktop Settings before trying again. Never delete the virtual disk file itself; it contains Docker’s data.

Why this helps

Removing unused images and build cache makes empty room inside Docker’s virtual disk. Compacting asks Windows to shrink the disk file so some empty room can become free space on C:. Docker’s WSL 2 guide explains where Docker keeps its WSL data and how the disk location can be changed.