All writing

Deleting files in WSL doesn't free your disk

Deleting 15 GB inside WSL and Docker freed nothing on C:. Getting the space back takes a trim, a shutdown and a compaction.

Code on GitHub

Where the space went

Okay, so I kept running out of space on C:, and deleting things inside WSL and Docker never seemed to help. The time I finally sat down to work it out, C: was at 98%, with 5.1 GB free.

Most of what filled it was 2 files. One belonged to WSL, Windows’ own way of running Linux, and the other to Docker Desktop, which runs on top of it. Ubuntu’s ext4.vhdx was 37.3 GB with 23 GB of files inside it. Docker Desktop’s docker_data.vhdx was 25.2 GB, and 12.6 GB of that was build cache, the layers Docker keeps to make the next build faster.

So I cleared the build cache, and the package caches npm, npx and pip keep inside Ubuntu. That was 15.2 GB. C: didn’t move.

Here’s what’s going on. WSL 2 keeps each distro, an installed Linux such as Ubuntu, in a virtual disk file: one file on Windows that Linux uses as a whole disk. Docker Desktop keeps its images, containers and volumes in another. Each file grows as Linux writes to it. When Linux deletes something, ext4, the filesystem inside the file, marks the space free in its own records, and the file on C: stays the size it was. Windows can’t see that anything changed.

Turns out plenty of people run into this. The WSL issue asking for that space to go back to Windows on its own was opened in 2019, and it’s still open with hundreds of comments. On Docker’s side, an issue from 2016 about its disk not shrinking after every image and container is deleted is still open too. People have written scripts to compact these disks in the meantime.

Getting the space back to C: takes 2 more steps. A trim tells the disk which blocks are free, and a compaction cuts those blocks out of the file.

after deleting files 8 blocks after a trim 8 blocks after compacting 5 blocks data free, still in the file trimmed
Deleting frees space in Linux's own records. A trim marks the empty blocks, and compacting removes them from the file. A block with any data left in it stays.

Trim, from the distro that owns the disk

Compacting returns little unless each disk was first trimmed from inside the distro that owns it. In Linux the command is fstrim:

sudo fstrim -av

It trims the filesystems mounted where it runs, and Docker’s disk isn’t mounted in Ubuntu. It belongs to docker-desktop, the distro Docker Desktop runs in, which mounts it at /mnt/docker-desktop-disk. A trim in Ubuntu doesn’t reach it.

You can see it in the numbers. Compacting Docker’s disk after a trim in Ubuntu returned 0.9 GB. Trimming inside docker-desktop and compacting again returned 7.6 GB.

trim in Ubuntu trim in docker-desktop fstrim Ubuntu disk Docker disk fstrim Ubuntu disk Docker disk then compact Docker's disk 0.9 GB back then compact Docker's disk 7.6 GB back
A trim reaches the filesystems mounted in the distro it runs in. Docker's disk is mounted in docker-desktop, and after a trim from there its compaction returned 7.6 GB instead of 0.9.

So Docker’s disk is trimmed from inside docker-desktop:

wsl -d docker-desktop -u root fstrim -v /mnt/docker-desktop-disk

-u root runs it as root, Linux’s administrator, so it never stops to ask for a password. If you script this, watch out for -e. It runs the program directly, without your shell and its startup files, and it also looks the program up without /usr/sbin and /sbin, where fstrim lives:

execvpe(fstrim) failed: No such file or directory

Going through sh -c finds it, and a non-interactive sh still reads no startup files:

wsl -d Ubuntu -u root -e sh -c 'fstrim -av'

Compacting needs everything stopped

A disk file can only be compacted while nothing has it open. That means stopping Docker Desktop, then shutting WSL down, which closes every WSL window, including a terminal you might be typing in.

wsl --shutdown

Optimize-VHD compacts a disk file in one command. It comes with the PowerShell module for Hyper-V, Windows’ virtual machine platform, and runs from an administrator window:

Optimize-VHD -Path "$env:LOCALAPPDATA\Docker\wsl\disk\docker_data.vhdx" -Mode Full

Home editions don’t have that module. There, diskpart, the disk tool built into Windows, compacts it with the disk attached read-only:

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

WSL can also make a disk sparse, so the file shrinks as Linux deletes. I tried that too, and current releases refuse:

> wsl --manage Ubuntu --set-sparse true
Sparse VHD support is currently disabled due to potential data corruption.

With both disks trimmed from their own distros and compacted, C: went from 5.1 GB free to 23 GB.

It returns less than the gap

Since this kept happening, I put the steps in order in a tool, unbloat. Its first version had a checklist that estimated each compaction as the gap between the disk file’s size and the space in use inside it. A real run on the same machine tested that.

Ubuntu 33.7 GB file, 21.6 GB in use up to 12.1 GB 4.6 GB back Docker 16.7 GB file, 13.5 GB in use up to 3.2 GB nothing back checklist estimate returned by compacting
Each estimate was the disk file's size minus the space in use inside it. Docker's disk had been compacted the night before.

Part of the difference is how a disk file gives space back. The file is made of blocks, 1 MB each on both of these, and a block with any data in it stays in the file. ext4 spreads files and its own bookkeeping across the disk, so a lot of the free space sits in blocks that are partly full. After compacting, Ubuntu’s disk file was 29.1 GB for 20.6 GB of files.

So the checklist now shows each disk’s file size and how much of it is in use, and after the run the summary says how much each compaction returned.

What to leave alone

docker system df said 4.28 GB of volumes were 100% reclaimable. A volume is where a container keeps data that outlives it, and 2 of these held a project’s local Postgres database and Redis data. Reclaimable there means no container refers to the volume. There were no containers on the machine at the time, so every volume counted, including the data the project’s next docker compose up would expect to find.

Anonymous volumes can hold a database too. The official Postgres image declares its data directory as a volume, so a container started without a named one writes the database into a volume Docker names with a random hash, and docker volume prune removes unused anonymous volumes.

unbloat never offers a volume of either kind. It lists what it’s keeping and how much space that is.

The order

unbloat runs the steps in the order above, and shows what each one costs before anything runs:

  1. Clear the caches and Docker’s build cache.
  2. Trim each disk from inside its own distro.
  3. Stop Docker Desktop and shut WSL down, unless unbloat was started from inside WSL or the machine is on battery below 50%.
  4. Compact each disk whose trim worked.