Why your WSL2 disk file never shrinks, and how to get the space back

What is going on

Each WSL 2 distribution keeps its files inside a virtual hard disk, which shows up on Windows as an ext4.vhdx file. Microsoft says WSL 2 resizes these files automatically to fit what you store, and that in current versions each one is given a 1TB maximum (How to manage WSL disk space). That maximum is only a ceiling. The file on your C: drive grows as you use it.

Going the other way is the problem. Microsoft's documentation for the diskpart compact vdisk command explains that dynamically expanding virtual disks grow as you add files but do not shrink on their own when you delete files (compact vdisk). WSL users have raised the same thing in a GitHub issue titled "WSL 2 should automatically release disk space back to the host OS", which is still open at the time of writing (issue #4699).

In practice that means you can delete 40 GB inside Linux, Linux will report the space as free, and Windows will still show a huge ext4.vhdx. Nothing is broken. The free space is just stuck inside the virtual disk until you compact it.

Step 1: find the file and check what is really used

Microsoft gives this PowerShell snippet to find the .vhdx path for a distribution. Replace the name with yours (source):

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

To see how much of the virtual disk is used from the inside, Microsoft documents this command. If it does not work, it suggests running wsl --update or trying wsl df -h /:

wsl.exe --system -d <distribution-name> df -h /mnt/wslg/distro

The Size column shows the maximum, not what Windows is using. Microsoft notes that WSL always shows the default maximum even if your Windows disk is smaller (source). Compare the Used column with the size of the .vhdx file in File Explorer. A big gap is the space you can get back.

Step 2: clean up inside Linux first

Compacting can only return space that is already free inside the disk. So delete what you do not need before you compact, for example unused Docker images and old package caches. Two of our other guides cover those: Docker Desktop disk space on Windows and clearing npm, pip and NuGet caches.

Step 3: back up, then compact

First stop WSL. wsl --shutdown immediately ends all running distributions and the WSL 2 virtual machine (source). If you use Docker Desktop, quit it too. Microsoft's repair steps mention closing Docker Desktop to avoid a sharing violation error while working on the disk file (source).

wsl --shutdown

Option A: diskpart

Open Command Prompt as administrator, which is how Microsoft runs its diskpart steps for WSL. The compact vdisk command only works on a dynamically expanding disk that is detached or attached read-only (compact vdisk), and attach vdisk readonly attaches it read-only (attach vdisk). Use your own path from Step 1:

diskpart
select vdisk file="<pathToVHD>"
attach vdisk readonly
compact vdisk
detach vdisk
exit

Option B: Optimize-VHD

PowerShell has a cmdlet for the same job. It reclaims unused blocks and can finish without making the file smaller if nothing can be optimised. -Mode Full is only allowed when the disk is mounted read-only, and Microsoft notes the cmdlet needs the disk to be detached or attached read-only (Optimize-VHD). It comes from the Hyper-V PowerShell module, so it is only available where that module is installed.

Optimize-VHD -Path <pathToVHD> -Mode Full

Automatic shrinking: sparse VHD (experimental)

Microsoft added an experimental feature in 2023 meant to let the virtual disk shrink by itself. New disks can be made sparse with sparseVhd=true under [experimental] in .wslconfig, and an existing distribution with wsl --manage <distro> --set-sparse true (WSL September 2023 update, .wslconfig settings).

Stop it growing forever

The defaultVhdSize setting in .wslconfig sets the maximum size for the virtual disk that stores a distribution's file system, and it defaults to 1 TB (.wslconfig settings). Setting a lower cap means WSL will report out-of-space sooner, so pick a number you can live with.

Doing this without the command line

SpaceFree has a WSL and Docker compaction wizard. It lists your virtual disks and shows how much space is trapped in each one before you change anything. You can do everything on this page by hand; the app is there if you would rather see the numbers first. Download SpaceFree.