Proposal for #4699: opt-in VHDX compaction after WSL shutdown
Nobody has claimed this yet.
- Dominant language
- C++
- Stars
- 33.7k
- Forks
- 1.8k
- Avg merge
- 3d 17h
- Merged PRs (30d)
- 116
Description
Related to #4699.
That issue already covers the disk reclaim problem itself, so this is not meant as a duplicate feature request. The goal here is to propose a more concrete implementation path that seems safer and easier to reason about in practice.
## Summary
Introduce an **optional VHDX compaction step triggered after WSL shutdown**, instead of trying to compact dynamically while WSL is still running.
## Motivation
Right now, freeing space inside WSL does not automatically free space on the Windows side. Even after large amounts of data are deleted inside the distro, the host-side `.vhdx` can remain heavily inflated until the user manually compacts it.
In practice, reclaiming that space usually ends up looking like this:
- delete data inside WSL
- run `wsl --shutdown`
- compact the VHDX manually from Windows using `optimize-vhd`, `diskpart`, or another host-side workflow
That works, but it is not a great experience. It is easy to forget, depends on which Windows tools are available, and usually only gets done once the user is already running low on disk space.
I ran into this after generating a very large amount of logs inside WSL. After cleaning everything up, the distro looked fine from inside Linux, but the `.vhdx` on the Windows side was still huge and had to be compacted manually.
## Proposal
Instead of introducing live or dynamic compaction while WSL is still active, a more conservative approach could be:
> **Support optional compaction after WSL is fully stopped.**
### High-level behavior
- only evaluate compaction when:
- `wsl --shutdown` is called, or
- a distro has fully stopped
- only run compaction if:
- reclaimable space exceeds a threshold
- a cooldown period has elapsed since the last compaction
- feature is:
- opt-in
- disabled by default
## Why this approach
Trying to compact while WSL is still running seems much more complex and much more likely to create edge cases.
Triggering compaction after shutdown has some clear advantages:
- no active filesystem activity inside the distro
- no running workload competing with the compaction step
- lower risk around open handles or in-flight writes
- it matches the manual workflow many users already rely on today
So this would not introduce a completely new maintenance pattern. It would mainly automate the one that users already perform manually.
## Example configuration
Just as an illustration, this could potentially be exposed through `.wslconfig` or a similar mechanism:
```ini
[wsl2]
autoCompact=true
autoCompactThresholdGB=2
autoCompactCooldownHours=24
```
## Non-goals
This proposal is intentionally conservative. It does **not** aim to:
- compact while WSL is running
- compact on every shutdown unconditionally
- replace or conflict with other existing disk-management behavior
## Implementation considerations
Some areas that seem relevant:
- a trigger point after VM teardown in `wslservice`
- estimating reclaimable space before deciding whether to compact
- safe use of the existing host-side VHD compaction path
- logging when compaction:
- runs
- is skipped due to threshold
- is skipped due to cooldown
- interaction with Docker Desktop and other WSL-integrated workloads
## Open questions
- what is the safest and most reliable way to estimate reclaimable space?
- should this be global or per-distro?
- should compaction run synchronously during shutdown or as a deferred background task after shutdown?
## Closing thought
Overall, this feels like a practical middle ground: it avoids the complexity of live compaction while still solving a real usability issue by automating a shutdown-based reclaim workflow that already exists.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by examining the post-VM-teardown trigger point in wslservice and the existing host-side VHD compaction path. Then review how .wslconfig settings and Docker Desktop or other WSL-integrated workloads interact with shutdown. The work is not yet defined as complete until the open questions around scope, reclaimable-space estimation, cooldowns, and synchronous versus deferred execution are resolved.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- cpp
- Domain
- operating-systems
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100