Shrink the WSL disk image (ext4.vhdx) on Windows

WSL 2 keeps each Linux distribution in one file, ext4.vhdx. The file grows as Linux writes, up to a limit of 1 TB by default, and it does not shrink when you delete things inside. Getting the space back takes three steps:

1. Free space inside Linux.
2. Shut WSL down.
3. Compact the file from Windows.

This guide gives the commands for each. It is for Windows 11 and Windows 10 with WSL 2. Wipzy does not run on Windows yet. A version is in the works, and nothing here needs it.

Find the file and its size

In PowerShell, replace Ubuntu with the name of your distribution from wsl --list --verbose:

(Get-ChildItem -Path HKCU:\Software\Microsoft\Windows\CurrentVersion\Lxss | Where-Object { $_.GetValue("DistributionName") -eq 'Ubuntu' }).GetValue("BasePath") + "\ext4.vhdx"

This is the lookup Microsoft documents. It prints a path such as C:\Users\you\AppData\Local\Packages\CanonicalGroupLimited...\LocalState\ext4.vhdx. Check the size of the file:

(Get-Item "C:\path\to\ext4.vhdx").Length / 1GB

Then compare it with what Linux really uses:

wsl df -h /

If the file is 80 GB and df shows 25 GB used, there are 55 GB to win back. If the two numbers are close, compacting will gain little. The space is in use, and step 1 is where you need to work.

Step 1: free space inside Linux

Inside the distribution, find what is large:

du -h --max-depth=1 ~ 2>/dev/null | sort -hr | head -15

The usual suspects are the same as on any developer machine: node_modules folders, ~/.cache, ~/.npm, ~/.cargo, and Docker data if you run Docker Engine inside WSL. For the package manager's own downloads on Ubuntu or Debian:

sudo apt clean

When you have deleted what you do not need, tell the virtual disk which blocks are now free:

sudo fstrim -av

Step 2: shut WSL down

From PowerShell or Command Prompt:

wsl --shutdown

This stops every distribution and the WSL virtual machine. Save your work in Linux first. If Docker Desktop is running, quit it too, because it uses WSL.

Step 3: compact the file

With diskpart, on any edition of Windows

Open Command Prompt as administrator and start diskpart. Then, with the path from the first section:

select vdisk file="C:\path\to\ext4.vhdx"
attach vdisk readonly
compact vdisk
detach vdisk
exit

compact vdisk is the step that takes time, a few minutes for a large file.

With Optimize-VHD, on Pro and Enterprise

If the Hyper-V PowerShell module is installed, one line in PowerShell as administrator does the same:

Optimize-VHD -Path "C:\path\to\ext4.vhdx" -Mode Full

Check the file size again afterwards, then start your distribution as usual.

Sparse mode: automatic, and still experimental

WSL can mark a disk file as sparse, so that Windows gets freed blocks back without a manual compact:

wsl --manage Ubuntu --set-sparse true

Treat this one with care. Microsoft lists the matching setting, sparseVhd in .wslconfig, under experimental features, and it is off by default. For a period, WSL releases refused to enable sparse mode without an extra flag and warned of possible data corruption. If you try it, make an export first. And do not mix the two methods: a disk in sparse mode should not be compacted with Optimize-VHD.

The manual compact above is the dull, dependable way.

Docker Desktop has its own file

Docker Desktop on Windows stores its images and containers in a separate disk file under %LOCALAPPDATA%\Docker\wsl. The same logic applies: free space inside with the docker prune commands, quit Docker Desktop, run wsl --shutdown, then compact that file with diskpart.

On a Mac the same pattern has another name. The file is Docker.raw, and its story is in Docker.raw is huge on a Mac.

Keep the limit lower

The 1 TB default is a ceiling, not a reservation. If you would rather hear "disk full" inside Linux than run out of space on C:, set a lower ceiling for new distributions in %UserProfile%\.wslconfig:

[wsl2]
defaultVhdSize=100GB

To change the size of an existing disk, WSL 2.5 and later have wsl --manage <distribution> --resize <size>.