Draft: add manual VHDX compaction command for stopped WSL distros

[Guayamose]

Summary of the Pull Request

Related to #40243 and #4699.

This is an exploratory draft PR for a manual-only VHDX compaction path.

It adds a new manual command:

• wsl --manage <Distro> --compact

The command compacts the VHDX backing file for a stopped WSL 2 distro using the Windows Virtual Disk API.

This PR intentionally does not add automatic compaction yet.

PR Checklist

• Closes: Proposal for #4699: opt-in VHDX compaction after WSL shutdown #40243
• Communication: Discussed in Proposal for #4699: opt-in VHDX compaction after WSL shutdown #40243 and related to the long-standing disk reclaim request in WSL 2 should automatically release disk space back to the host OS #4699
• Tests: Added/updated and pass locally where applicable
• Localization: End-user facing strings added/updated
• Dev docs: Not added; this is currently an exploratory draft
• Documentation updated: Not yet; if this direction is accepted, docs can be added in the docs repo

Detailed Description of the Pull Request / Additional comments

Scope

Included:

• Adds an internal VHD compaction helper using OpenVirtualDisk and CompactVirtualDisk.
• Adds service/client plumbing for compacting a distro VHD.
• Adds wsl --manage <Distro> --compact.
• Rejects running distros / in-use VHDs.
• Preserves clear error behavior for ERROR_SHARING_VIOLATION.
• Adds tests for the manual command path.
• Updates help/localization strings.

Not included:

• No automatic compaction.
• No shutdown hook.
• No .wslconfig policy.
• No threshold/cooldown logic.
• No deferred retry/background task.
• No Docker-specific special casing.
• No special handling for Docker-managed VHDs.

Motivation

The broader issue in #4699 is that WSL 2 distro VHDX files can grow significantly and not release space back to the host automatically.

In #40243 I proposed a safer path around shutdown/offline compaction. Before attempting any automatic policy, this PR adds a smaller manual command first, so the Virtual Disk API integration and safety model can be reviewed independently.

Validation

Built successfully on Windows:

• cmake .
• cmake --build . --config Debug --target wsl wslservice wsltests -- /m
• cmake --build . --config Debug --target msixinstallerpackage -- /m

Tested:

• UnitTests::UnitTests::Compact passed.
• Manual compact against a stopped disposable Ubuntu WSL 2 distro succeeded.
• The distro booted successfully after compaction.
• Running distro case rejected as expected with Wsl/Service/WSL_E_DISTRO_NOT_STOPPED.
• wsl --manage Ubuntu --compact --resize 10GB did not compact and failed argument validation/help as expected.

Manual validation result:

• Command: wsl --manage Ubuntu --compact
• Output: La operación se completó correctamente.
• Exit code: 0
• VHD delta: -2,097,152 bytes
• Boot check command: wsl -d Ubuntu -- echo ok
• Boot check output: ok
• Boot check exit code: 0

Running distro validation:

• Command: wsl --manage Ubuntu --compact
• Error: Wsl/Service/WSL_E_DISTRO_NOT_STOPPED
• Exit code: -1
• VHD delta: 0

Notes

This is opened as a draft because the intended first step is design and maintainer feedback on the manual command surface and service/helper integration.

Open questions:

• Is wsl --manage <Distro> --compact the right CLI surface?
• Should this remain manual first before any automatic policy is considered?
• Should the helper report before/after size or keep output minimal?
• Should fixed/non-compactable VHDs get a more specific message?
• Are there preferred telemetry/logging patterns for this operation?

Future work, if this direction is acceptable:

• opt-in shutdown-triggered policy
• threshold/cooldown
• deferred retry/backoff
• richer telemetry/logging
• reclaim estimation

[Copilot]

Pull request overview

Adds a manual-only VHDX compaction path for stopped WSL 2 distributions, exposed via wsl --manage <Distro> --compact, with service plumbing and a Virtual Disk API helper.

Changes:

• Introduces --compact in wsl.exe --manage, routed through SvcComm to the service.
• Implements a service-side CompactDistribution path that rejects non-WSL2 and running/in-use distros and invokes CompactVirtualDisk.
• Updates help/localization text and adds a WSL2 unit test covering the compact flow.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
test/windows/UnitTests.cpp	Adds help text expectation and a new WSL2 test for --manage --compact.
src/windows/service/inc/wslservice.idl	Extends ILxssUserSession with CompactDistribution RPC method.
src/windows/service/exe/LxssUserSession.h	Declares CompactDistribution on the COM class + impl.
src/windows/service/exe/LxssUserSession.cpp	Implements CompactDistribution validation and VHD compaction call path.
src/windows/inc/wsl.h	Adds --compact manage option constant.
src/windows/common/WslCoreFilesystem.h	Declares CompactVhd helper.
src/windows/common/WslCoreFilesystem.cpp	Implements CompactVhd via OpenVirtualDisk + CompactVirtualDisk.
src/windows/common/WslClient.cpp	Adds CLI parsing/dispatch for --manage --compact.
src/windows/common/svccomm.hpp	Adds SvcComm::CompactDistribution declaration.
src/windows/common/svccomm.cpp	Wires SvcComm::CompactDistribution to ILxssUserSession.
localization/strings/en-US/Resources.resw	Adds --compact help text + locked token list update.
localization/strings/es-ES/Resources.resw	Adds Spanish --compact help text + locked token list update.

[Guayamose]

@microsoft-github-policy-service agree

[Copilot]

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 33 out of 33 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 33 out of 33 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 33 out of 33 changed files in this pull request and generated no new comments.

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[Guayamose]

Sorry for the Copilot mess, I thought it was the automatic review, but it was my settings.

[benhillis]

This is looking pretty good, let me discuss with some of the team to see what we want to do here. We've internally been looking at some options to reclaim vhd disk space automatically, but even so it's probably a good idea to have a manual option too.

Thanks for the contribution!

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 4 comments.

[Guayamose]

All the four above are contradictions to the maintainer

[Guayamose]

This is looking pretty good, let me discuss with some of the team to see what we want to do here. We've internally been looking at some options to reclaim vhd disk space automatically, but even so it's probably a good idea to have a manual option too.

Thanks for the contribution!

Thanks.

My plan was to start with this manual --compact command as a small safe primitive, then continue toward the automatic reclaim direction once the lower-level API/service path was validated.

I understand the team may want to drive the automatic part internally. I’ll keep this PR focused on the manual path and adapt based on the direction you prefer.

[dporf]

@benhillis

We've internally been looking at some options to reclaim vhd disk space automatically

Hello. The best way to reclaim vhd disk space would be mapping VM's BLKDISCARD ioctl to host's FSCTL_SET_ZERO_DATA if sparse mode enabled. This way disk space may be deallocated without manual compaction, without moving data back and forth, unused data will be freed even without stopping VM (on the fly, scheduled or manually by calling fstrim utility).

[Guayamose]

@dporf

Hello. The best way to reclaim vhd disk space would be mapping VM's BLKDISCARD ioctl to host's FSCTL_SET_ZERO_DATA if sparse mode enabled. This way disk space may be deallocated without manual compaction, without moving data back and forth, unused data will be freed even without stopping VM (on the fly, scheduled or manually by calling fstrim utility).

So, what you said makes sense and its probably a better long term solution and more comfortable for users, but in my opinion this would be more of an architectural change rather than a small addon or replacement for de manual compaction.

Mapping guest BLKDISCARD/TRIM operations directly to host-side sparse deallocation would move space reclamation into the live I/O path. That means WSL would need to handle discard batching, ordering, error handling, host filesystem behavior, and compatibility with existing VHDX files very carefully.

It could also make the backing file layout less predictable over time, since space would be punched out dynamically as the guest filesystem frees blocks. Depending on the frequency and pattern of discards, that could introduce host-side fragmentation or metadata overhead that is harder to reason about than an explicit offline compaction pass.

So while the idea is technically possible, I think it has a much larger correctness and regression surface than the stopped-VM compaction operation.

[dporf]

@Guayamose hey, I'm just trying to be heard by WSL team member

[ptrivedi]

@Guayamose hey, I'm just trying to be heard by WSL team member

@dporf: Thank you for reporting, we hear you. A team member internally has been actively looking at this area and we have shared your PR with them. Manual option is good to have too.. we will get back to you shortly.