Docker WSL ext4.vhdx File Size Management

When using Docker Desktop with WSL 2 on Windows, you may notice that the ext4.vhdx file continues to consume significant disk space even after removing all containers, images, and volumes. This article explains why this happens and provides comprehensive solutions for reclaiming that space.

The Problem: Why VHDX Files Remain Large

WSL 2 uses dynamic virtual hard disk (VHDX) files that:

• Start with minimal initial size
• Expand automatically as you add data
• Do not automatically shrink when you remove data

This means that even after running docker system prune -a and removing all dangling volumes, the virtual disk file maintains its maximum allocated size.

INFO

The ext4.vhdx file typically resides in:

• %LocalAppData%\Docker\wsl\data\ext4.vhdx for Docker data
• Or in your WSL distribution's package directory

Solution 1: Docker Desktop's Built-in Cleanup

The simplest method to reclaim space is using Docker Desktop's built-in cleanup tool:

1. Open Docker Desktop
2. Click the question mark (?) icon in the title bar
3. Select Clean / Purge data
4. Ensure "WSL 2" is checked in the modal that appears
5. Confirm the operation

WARNING

This will completely remove all Docker data, including images, containers, and volumes. Back up any important data first.

Solution 2: Manual VHDX Optimization

For more control over the process, you can manually optimize the virtual disk.

Prerequisites

• Stop all Docker services and WSL instances:

  wsl --shutdown

Method A: Using Optimize-VHD (Windows Pro/Enterprise)

1. Open PowerShell as Administrator
2. Run the optimization command:

   Optimize-VHD -Path "${Env:LocalAppData}\Docker\wsl\data\ext4.vhdx" -Mode Full

Method B: Using DiskPart (All Windows Editions)

1. Open Command Prompt as Administrator
2. Shut down WSL:

   wsl --shutdown

3. Verify WSL is stopped:

   wsl --list --verbose

4. Start DiskPart:

   diskpart

5. Within DiskPart:

   select vdisk file="C:\path\to\your\ext4.vhdx"
   compact vdisk
   exit

TIP

To find your VHDX file path, check:

• Docker data: %LocalAppData%\Docker\wsl\data\ext4.vhdx
• WSL distributions: %LocalAppData%\Packages\<DistributionPackage>\LocalState\ext4.vhdx

Solution 3: Complete Docker WSL Reinstallation

If you don't need to preserve any Docker data:

1. Uninstall Docker Desktop
2. Open PowerShell and remove the WSL distributions:

   wsl --unregister docker-desktop
   wsl --unregister docker-desktop-data

3. Reinstall Docker Desktop

DANGER

This approach will permanently delete all Docker images, containers, and volumes. Only use this if you have no data to preserve.

Solution 4: Automated Tools

WSL Compact Utility

The wslcompact tool provides a convenient way to manage multiple WSL distributions:

# Install via PowerShell
iwr -useb https://raw.githubusercontent.com/okibcn/wslcompact/main/wslcompact.ps1 | iex

# Run to see estimated space savings
wslcompact

Linux fstrim Command

From within your WSL distribution, you can run:

sudo fstrim -av

This tells the hypervisor to deallocate empty blocks from the virtual disk.

Solution 5: Experimental Sparse VHD Feature

WSL 2.0.0+ includes an experimental sparse mode that automatically shrinks VHDX files:

# Convert existing distribution to sparse mode
wsl --manage <distro-name> --set-sparse true

# Enable sparse mode for new distributions
# Add to %UserProfile%\.wslconfig:
[experimental]
sparseVhd=true

Experimental Feature

The sparse VHD feature is still experimental and has reports of potential filesystem corruption. Use with caution and maintain backups.

Prevention and Best Practices

1. Regular maintenance: Periodically clean up unused Docker resources
2. Monitor disk usage: Keep an eye on your VHDX file size
3. Use volumes wisely: Store large datasets in mounted volumes instead of the container filesystem when possible
4. Backup important data: Before performing any optimization, ensure critical data is backed up

Conclusion

The Docker WSL ext4.vhdx file doesn't automatically shrink because of how dynamic virtual disks work in WSL 2. While this behavior is by design, several effective methods exist to reclaim disk space—from Docker Desktop's built-in tools to manual optimization techniques.

For most users, the Docker Desktop cleanup option provides the simplest solution, while advanced users may prefer the manual optimization methods for more control over the process.