microsoft / microsoft/WSL

Proposal for #4699: opt-in VHDX compaction after WSL shutdown

Open
#40,243 12 comments 28 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

feature
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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.