🐳 Docker VHDX Optimizer

An interactive guide to shrinking and auto-compacting your bloated Docker WSL2 virtual disk, reclaiming gigabytes of lost hard drive space.

The Problem: Virtual Bloat

This section illustrates the core issue with Docker Desktop on Windows. When you pull images or build containers, the .vhdx file expands dynamically. However, when you delete data inside Docker, Windows does not automatically reclaim that space. The chart below demonstrates the hidden "bloat" that occupies your physical hard drive.

Disk Status
Currently showing an unoptimized, bloated VHDX file occupying 100GB of physical space for only 25GB of real data.

The Solution: Interactive Action Plan

This section provides the actionable steps to fix the bloat shown on the left. Follow Phase 1 to clean Docker internally, then choose Phase 2 for an immediate manual shrink, or Phase 3 to enable a permanent auto-shrinking feature in Windows. Click the copy icons to grab the commands.

Phase 1: Free Space Inside Docker

Before shrinking the virtual disk from Windows, we must tell Docker to free up internal blocks. Run these commands in your standard terminal.

Clear containers & images 
docker system prune -a --volumes
Clear buildx cache 
docker builder prune -a

Phase 2: Manual Shrink via Diskpart

Use this method for an immediate disk shrink. Ensure Docker Desktop is completely quit before starting.

⚠️ Prerequisite: Open PowerShell as Administrator and shut down WSL first:

wsl --shutdown

Run these commands sequentially in Administrator PowerShell:

diskpart
select vdisk file="C:\Users\<YOUR_USERNAME>\AppData\Local\Docker\wsl\disk\docker_data.vhdx"
attach vdisk readonly
compact vdisk
detach vdisk
exit

* Note: Depending on your install, the file might also be named ext4.vhdx inside the \wsl\data\ folder.

Phase 3: Enable Auto-Shrink (Pro-Tip)

Skip `diskpart` forever. Enable Sparse VHD in WSL2 to force Windows to automatically shrink the disk in the background when you delete Docker data.

Step 1: Identify your Docker distro name

List Distros 
wsl --list --verbose

Look for 'docker-desktop' or 'docker-desktop-data' and ensure it says 'Stopped'.

Step 2: Force enable Sparse mode

Using `--allow-unsafe` bypasses a strict Windows safeguard. It is perfectly safe as long as the distro state is 'Stopped'.

Enable Sparse VHD 
wsl --manage docker-desktop --set-sparse true --allow-unsafe

Swap 'docker-desktop' with your exact distro name from Step 1 if different.