Reclaiming Hard Disk Space Used by Docker on Windows

Understanding Where Docker Stores Data

Docker Desktop for Windows relies on a lightweight Linux virtual machine running inside WSL2 (Windows Subsystem for Linux 2). The primary culprit for excessive disk usage is the ext4.vhdx file associated with the default WSL distribution used by Docker. Unlike standard files that shrink when data is deleted, VHDX files only grow; they do not automatically release freed space back to the host operating system.

Additionally, Docker maintains a local registry of images, containers, volumes, and build caches. Over time, stopped containers and dangling images accumulate, further contributing to storage consumption. While the Docker CLI can clean up these artifacts, it cannot reduce the size of the already allocated VHDX file. Therefore, a two-pronged approach is necessary: cleaning Docker artifacts and compacting the virtual disk.

Identifying the VHDX Location

The VHDX file is typically stored in the following path within your user directory:

%LOCALAPPDATA%\Docker\wsl\data\ext4.vhdx

If you are using a custom WSL distribution or have migrated your data, the location might vary slightly. You can verify the active WSL instance by opening PowerShell and running wsl -l -v. Look for the state of the docker-desktop and docker-desktop-data distributions. If these states show as Running, you must stop them before proceeding with any low-level disk operations.

Step-by-Step Cleanup Process

Follow these steps to safely reclaim disk space. Ensure you have backed up any critical data within your containers, as this process will remove all containerized data.

1. Stop Docker Desktop: Right-click the Docker icon in the system tray and select "Quit Docker Desktop." Alternatively, use the task manager to end the Docker Desktop.exe process if it does not close normally.
2. Shutdown WSL Instances: Open PowerShell as an administrator and run the following command to ensure no background processes are locking the VHDX file:

wsl --shutdown

This command forces all WSL2 instances to terminate immediately. Verify that the processes are gone by checking Task Manager or running wsl -l -v again; the status should be Stopped.

3. Delete Old Artifacts via Docker: Before touching the VHDX, use Docker's built-in cleanup commands to remove unnecessary objects. Run:

docker system prune -a

This removes stopped containers, unused networks, dangling images, and build cache. Note that this operation deletes all images, so you may need to pull them again later. If you want to keep specific images, avoid the -a flag or manage them individually.

4. Compact the VHDX File: Since deleting data inside the VM does not shrink the .vhdx file, you must compact it externally. First, navigate to the folder containing the VHDX file. Then, use the vhdutil tool or PowerShell cmdlets to compact the disk. For example, in PowerShell:

Optimize-VHD -Path "%LOCALAPPDATA%\Docker\wsl\data\ext4.vhdx" -Mode Full

This process may take several minutes depending on the size of the file. Once completed, check the file size; it should now reflect the actual used space rather than the maximum allocated capacity.

Preventing Future Bloat

To maintain optimal disk usage, consider configuring Docker to limit resource allocation. In Docker Desktop settings, under "Resources," you can set limits for CPU and memory, which indirectly helps manage the footprint of the WSL2 VM. Additionally, regularly running docker system prune as part of your maintenance routine prevents the accumulation of orphaned resources.

If you frequently work with large datasets or persistent volumes, consider mounting host directories directly into containers rather than storing data inside the container layer. This keeps the internal database lean and reduces the growth rate of the ext4.vhdx file. For more detailed guidance on managing WSL2 disk sizes, refer to our guide on optimizing WSL2 Docker VHDX file size.

Another common issue arises when Hyper-V features conflict with Docker's networking stack. Ensuring that Hyper-V is correctly enabled can prevent unexpected storage allocations due to failed virtual network adapters. Check our article on enabling Hyper-V for Docker Desktop to resolve related virtualization errors.

Frequently Asked Questions

Why doesn't Docker automatically shrink the VHDX file?

VHDX files are dynamic disks that expand as needed but do not contract automatically when data is deleted inside the guest OS. This behavior is inherent to how virtual hard disks handle sparse files and fragmentation. Manual compaction is required to return the freed space to the Windows host.

Is it safe to delete the ext4.vhdx file manually?

Deleting the file directly while Docker is running can corrupt your installation. You must ensure Docker Desktop is fully quit and WSL2 is shut down before removing or modifying the file. It is safer to compact the file rather than delete it entirely, unless you intend to reinstall Docker from scratch.

How can I check the current size of my Docker data?

You can use the command docker system df to view a summary of disk usage by images, containers, volumes, and build cache. For the total disk impact including the VHDX file, check the file size in %LOCALAPPDATA%\Docker\wsl\data\ using Windows Explorer or PowerShell.

Can I move the Docker data folder to another drive?

Yes, you can migrate the Docker data folder to another drive by changing the WSL2 configuration or symlinking the data directory. This requires stopping Docker, moving the data folder, and updating the symbolic link or configuration paths. This is useful if your C: drive has limited space.

What happens to my containers after pruning?

Pruning removes stopped containers and unused images. Any running containers remain unaffected until you explicitly stop them. However, if you use the -a flag with docker system prune, all images are removed, meaning you will need to pull them again to restart previous services.