Shrink WSL2 and Docker Virtual Disks to Reclaim Disk Space

Over time, WSL2 distributions and Docker images can consume significant disk space on your Windows system. Even after deleting files, containers, or images, the allocated virtual disk (VHDX) files do not automatically shrink to reflect the freed space. This comprehensive guide explains how to manually reclaim disk space by optimizing these virtual disks.

Understanding the Problem

WSL2 and Docker Desktop use VHDX (Virtual Hard Disk) files to store their data. These files have a tendency to grow but rarely shrink automatically, leading to:

• Wasted disk space even after cleanup
• Performance degradation on systems with limited storage
• Unexpected “disk full” errors despite having deleted content

The solution is to manually optimize these VHDX files using Windows’ built-in tools.

Shrinking WSL2 Virtual Disks

Step 1: Locate the VHDX File

On Windows 11, WSL2 distributions store their virtual disks in the following location:

C:\Users\[username]\AppData\Local\Packages\

Look for the vendor name corresponding to your installed distribution:

Once you identify the correct folder, navigate to the LocalState subdirectory, where you will find the ext4.vhdx file for the distribution.

Step 2: Prepare for Optimization

Before optimizing the VHDX file, ensure you:

1. Save your work and close all WSL2 sessions
2. Stop all running containers if using Docker
3. Create a backup of important data (optional but recommended)

Step 3: Optimize the Virtual Disk

1. Shut down WSL2 completely:

   wsl --shutdown
   

2. Open PowerShell as Administrator and run the optimization command:

   optimize-vhd -Path "C:\Users\[username]\AppData\Local\Packages\[vendor-folder]\LocalState\ext4.vhdx" -Mode full
   

   Example for Ubuntu:

   optimize-vhd -Path "C:\Users\johndoe\AppData\Local\Packages\CanonicalGroupLimited.Ubuntu22.04LTS_79rhkp1fndgsc\LocalState\ext4.vhdx" -Mode full
   

Shrinking Docker Virtual Disks

Step 1: Locate Docker’s Virtual Disks

Docker Desktop stores its virtual disk files for WSL2 in these locations:

C:\Users\[YOURNAME]\AppData\Local\Docker\wsl\disk\
C:\Users\[YOURNAME]\AppData\Local\Docker\wsl\data\

The main files you’ll typically find:

• data.vhdx - Contains Docker images and containers
• disk.vhdx - Contains Docker’s Linux filesystem

Step 2: Clean Docker Resources (Optional)

Before shrinking, consider cleaning up unused Docker resources:

# Remove unused containers, networks, images, and volumes
docker system prune -a --volumes

# Remove specific items
docker container prune  # Remove stopped containers
docker image prune -a   # Remove unused images
docker volume prune     # Remove unused volumes

Step 3: Optimize Docker Virtual Disks

1. Shut down Docker completely:

   wsl --shutdown
   

2. Close Docker Desktop from the system tray

3. Open PowerShell as Administrator and optimize both VHDX files:

   # Optimize data disk
   optimize-vhd -Path "C:\Users\[YOURNAME]\AppData\Local\Docker\wsl\data\ext4.vhdx" -Mode full
      
   # Optimize disk if present
   optimize-vhd -Path "C:\Users\[YOURNAME]\AppData\Local\Docker\wsl\disk\disk.vhdx" -Mode full
   

Advanced Tips and Troubleshooting

Monitoring Disk Usage

Before and after optimization, check the actual file sizes:

# Check VHDX file size
Get-ChildItem "C:\Users\[username]\AppData\Local\Packages\*\LocalState\*.vhdx" | 
    Select-Object Name, @{Name="Size(GB)";Expression={[math]::Round($_.Length/1GB,2)}}

Alternative: Using diskpart

If optimize-vhd is not available, you can use diskpart:

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

Preventing Future Bloat

1. Regular cleanup: Schedule periodic cleanup of unused Docker resources
2. Use .dockerignore: Prevent unnecessary files from being included in images
3. Multi-stage builds: Use Docker multi-stage builds to reduce final image size
4. WSL2 management: Regularly clean up packages and logs in WSL2 distributions

Troubleshooting Common Issues

“Access Denied” Error:

• Ensure PowerShell is running as Administrator
• Make sure WSL2 and Docker are completely shut down
• Check if any antivirus software is locking the files

“File is in use” Error:

• Run wsl --shutdown and wait 10-15 seconds
• Close Docker Desktop completely
• Check Task Manager for any remaining wsl.exe or docker processes

Limited Space Reclaimed:

• Some VHDX files have minimum size limits
• Recent file writes may prevent significant shrinking
• Consider the VHDX file’s allocation unit size

Performance Impact and Results

After optimization, you should expect:

• Significant disk space recovery (often 50-80% reduction)
• Faster boot times for WSL2 distributions
• Improved overall system performance on storage-constrained systems
• Better Docker performance due to optimized disk access

Conclusion

Regular maintenance of WSL2 and Docker VHDX files is essential for optimal system performance and storage management. By following this guide, you can reclaim substantial disk space and maintain a clean, efficient development environment.

The optimization process is safe and can be performed regularly without data loss, though creating backups of critical data is always recommended as a best practice.

📝 Original Gist: This tutorial is based on my original GitHub Gist with expanded content and additional troubleshooting tips.

Pro Tip: Consider creating a PowerShell script to automate this process for multiple VHDX files, making regular maintenance even easier!