How WSL 2 VHDX Files Grow and Reclaim Windows Space

For developers who build containers, install toolchains, compile large projects, or regularly delete caches, this distinction can become expensive. A distribution may once have held tens of gigabytes of packages, build outputs, and temporary data, then report plenty of free space after cleanup. Yet Windows storage may not immediately return to the same baseline.

The important qualification is that this is normal behavior for an ordinary dynamically expanding WSL virtual disk, not a universal and permanent rule for every WSL configuration. Microsoft has also developed an experimental sparse-VHD approach intended to reclaim space automatically. Its current safety status, however, makes manual expectations and careful backups especially important.

Why df -h and Windows storage can tell different stories​

Each WSL 2 Linux distribution uses a virtual hard disk represented on the Windows host by an ext4.vhdx file. Linux sees the ext4 filesystem contained within that file. Windows sees the VHDX itself as a host-side file consuming capacity on an NTFS volume.

That produces two different measurements:

• Linux filesystem usage: How much of the virtual ext4 disk is occupied by files and how much space remains available inside it.
• Windows physical usage: How much space the VHDX file currently occupies on the Windows drive.

A dynamically expanding VHD grows as data is written into it. Deleting data from Linux makes those filesystem blocks available for reuse inside the distribution, but it does not automatically mean that the VHDX file becomes physically smaller on the host.

This is why a cleanup can look successful in a Linux terminal but fail to create an equivalent amount of free space in Windows. Both readings can be accurate; they answer different questions.

The distinction also prevents a common mistake: treating the virtual disk’s maximum capacity as though it were its present Windows footprint. A VHDX can have room to grow inside Linux without currently consuming that entire amount on the host. Conversely, a VHDX can retain a large physical footprint after its Linux filesystem has become mostly empty.

First, identify the distributions that actually use WSL 2​

Before investigating storage, establish which installed distributions use WSL 2. The appropriate command is:

wsl --list --verbose

This lists installed distributions, their running state, and whether each uses WSL 1 or WSL 2. That last column matters: the VHDX discussion applies to WSL 2 distributions.

It is useful to keep WSL’s other status commands separate in your troubleshooting notes:

• wsl --list --verbose identifies individual distributions and their WSL 1 or WSL 2 version.
• wsl --status provides general WSL configuration information.
• wsl --version reports WSL component versions.

These commands are often grouped together in advice posts, but they are not interchangeable. In particular, wsl --status should not be treated as the authoritative per-distribution check for whether a particular distro is WSL 2.

A practical inventory starts with the distributions you recognize: a daily development distro, old test installations, and any container-related environment that may have created or retained substantial data. An idle distribution is not necessarily a small one.

Do not rely on a guessed AppData path​

WSL storage paths vary by distribution type and installation history. Guessing a package-folder path is risky, especially when several distributions or user accounts are involved.

Microsoft documents a registry-based PowerShell expression that retrieves a named distribution’s BasePath and then appends ext4.vhdx. That documented route is preferable to assumptions about a particular AppData subfolder.

However, locating a VHDX is not permission to treat it as an ordinary data file. Microsoft explicitly warns users not to modify, move, or access WSL-related files under AppData with Windows tools or editors, because doing so can corrupt the distribution.

That warning creates an important practical boundary. Inspecting disk use is one task; editing, copying, relocating, mounting casually, or opening the VHDX in third-party software is another. A manual compaction workflow is advanced maintenance, not routine file management. It should be attempted only after a backup or export has been created and tested well enough that the distribution can be restored if something goes wrong.

What manual compaction is designed to do​

Windows includes DiskPart functionality for compacting a dynamically expanding VHD. The documented purpose of compact vdisk is to reduce a dynamic VHD’s physical size.

There are two conditions that should shape expectations:

1. The VHD must be dynamically expanding.
2. It must be detached or attached read-only before DiskPart can compact it.

In a WSL scenario, that means WSL must not still have the distribution’s disk in active use. The appropriate preparation command is:

wsl --shutdown

This immediately terminates all running distributions and the WSL 2 lightweight utility virtual machine. That is stronger than merely closing one terminal window, and it is the relevant prerequisite before host-side VHD work.

At a high level, the DiskPart flow is to select the intended VHDX, attach it read-only if needed, issue compact vdisk, and then detach it. The basic commands look like this once the correct VHDX path has been established:

select vdisk file="<path to ext4.vhdx>"
attach vdisk readonly
compact vdisk
detach vdisk

The sequence must be aimed at the exact VHDX for the intended distribution. A typo or a guessed path is unacceptable when the object being selected is a virtual disk containing a Linux installation.

Afterward, launch the distribution normally and check that expected projects, packages, and services still work. A reclaimed number in Windows storage is not a complete success criterion; data integrity is the first one.

Compaction is not a guaranteed space-recovery button​

The word “compact” can create unrealistic expectations. It means Windows will attempt to reduce the physical size of the eligible dynamic VHD; it does not promise that every cleanup produces a dramatic drop in the VHDX file’s size.

How much space can be recovered is not established by a simple formula in the available documentation. It depends on the VHD’s allocation history and whether reclaimable blocks are available. A distribution that has accumulated and deleted large amounts of data may be a stronger candidate than one whose disk is still actively occupied, but neither case guarantees a particular result.

That uncertainty has several consequences:

• Do not promise users that deleting a given number of gigabytes in Linux will return the same number to Windows.
• Do not interpret little or no reduction as proof that DiskPart failed.
• Do not judge a potential maintenance window solely by the size reported from inside the distro.
• Do not use a one-off result from another machine as a prediction for your own.

Manual compaction can still be valuable when a known dynamic VHDX has retained storage after substantial deletions. It is simply a maintenance operation with variable returns and meaningful data-risk considerations—not a substitute for storage planning.

The sparse-VHD exception—and why caution still wins​

It is inaccurate to say that WSL can never give space back automatically. Microsoft introduced an experimental sparse-VHD feature designed to automatically shrink the WSL virtual disk as it is used. Documentation described it as opt-in, with sparse VHD disabled by default, and provided management controls for existing distributions.

That history matters because it shows that automatic reclaim is a real design direction rather than a technical impossibility.

But it is not a sound basis for broadly recommending that users enable sparse VHD today. Current WSL source code retrieved for this review indicates that creation of sparse VHDs is disabled while potential data corruption is being investigated. When the sparse option is requested, the code disables it and emits a warning.

There is an unavoidable gap between an experimental feature’s published introduction and its safe, currently working availability in a particular installed WSL release. The available material does not establish the exact release boundary at which behavior may change again. Until Microsoft clearly resolves the corruption issue and the feature is demonstrably enabled in the relevant build, automatic sparse reclaim should be viewed as a feature to monitor, not a storage-management strategy to depend on.

The cautious conclusion is more useful than either extreme: ordinary dynamic VHDX files generally do not shrink merely because Linux files were deleted; sparse VHDs were intended to change that; and current safety signals make it unwise to assume the sparse path is ready for general use.

Avoid unverified “one-click” scripts​

Storage problems naturally attract PowerShell automation, and scripts can reduce repetitive work. But a script that touches WSL VHDX files combines elevated Windows disk operations with data that may be essential to a development environment. Its name, repository, parameters, maintenance status, and recovery guidance all matter.

A similarly named public script has been found that can discover VHDX files, optionally run filesystem trimming, shut down WSL, and compact VHDX files. Its visible switches do not match claims made for another purported optimizer workflow. That is not enough to validate any specific tool or to recommend a copied command line.

Treat claims about an optimizer’s inventory mode, per-distro selection, engine choices, or warnings as unverified unless you can inspect the actual code and documentation for the exact project. The safer rule is simple: never run an administrator-level disk-maintenance script because a blog post says its parameters are convenient.

For teams, that also means versioning any approved maintenance script internally, reviewing the exact operations it performs, documenting the backup requirement, and testing it against a disposable distribution before using it on a developer’s primary environment.

A conservative WSL storage routine​

The least risky approach is not to compact every distribution on a schedule. Instead, use a decision process:

1. List distributions and confirm which are WSL 2.
2. Identify whether Windows storage pressure is real and whether old WSL workloads are plausible contributors.
3. Clean unneeded data inside the relevant Linux distribution first.
4. Recognize that Linux free space is not proof of host-side reclamation.
5. Create and validate a backup or export before any host-side VHD operation.
6. Shut down WSL completely before attempting DiskPart work.
7. Compact only the specifically identified dynamic VHDX, read-only or detached as required.
8. Detach it when finished, then validate the distro after restart.
9. Record the before-and-after Windows footprint, while accepting that the result may be modest.

This workflow is deliberately less dramatic than “delete files and recover everything.” It is also better aligned with how virtual disks work and with the consequences of a mistake.

Bottom line​

A large WSL 2 footprint is often explained by a dynamic ext4.vhdx that grew during prior workloads and did not automatically shrink when Linux files were deleted. The key diagnostic insight is to separate free space inside ext4 from physical space consumed by the VHDX on Windows.

DiskPart provides a manual compaction mechanism for eligible dynamic VHDs after WSL has been shut down, but recovery is not guaranteed and WSL’s own files should be handled with exceptional care. Sparse VHDs point toward automatic reclaim, yet their present corruption-related safety status means they should not be assumed to solve the problem today.

For Windows users, the best outcome is not merely a smaller number in storage settings. It is a smaller number achieved with a known backup, the right target disk, a clean shutdown, realistic expectations, and a working Linux environment afterward.