Draft: add manual VHDX compaction command for stopped WSL distros by Guayamose · Pull Request #40481 · microsoft/WSL

Rafa Pradillo (Guayamose) · 2026-05-10T02:44:48Z

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.

Rafa Pradillo (Guayamose) · 2026-05-10T02:56:31Z

@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

Pull request overview

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

Copilot

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

Copilot

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

Rafa Pradillo (Guayamose) · 2026-08-10T17:39:22Z

Change looks good overall, minor comments

Blue (@OneBlue) Done, Thanks.

Copilot

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

Blue (OneBlue) · 2026-08-10T18:58:50Z

/azp run

azure-pipelines · 2026-08-10T18:59:01Z

Azure Pipelines: Successfully started running 1 pipeline(s).

Copilot

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

Copilot

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

Rafa Pradillo (Guayamose) · 2026-08-10T22:52:57Z

Blue (@OneBlue) Formatting is fixed. Could you run "/azp run" again please?

Blue (OneBlue) · 2026-08-10T23:10:17Z

/azp run

azure-pipelines · 2026-08-10T23:10:28Z

Azure Pipelines: Successfully started running 1 pipeline(s).

Copilot

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

Rafa Pradillo (Guayamose) · 2026-08-11T08:53:22Z

Blue (@OneBlue) Sorry again, It should pass now.

Rafa Pradillo (Guayamose) requested a review from a team as a code owner May 10, 2026 02:44

Copilot AI lite review requested due to automatic review settings May 10, 2026 02:44

Copilot started reviewing on behalf of Rafa Pradillo (Guayamose) May 10, 2026 02:45 View session

Copilot AI reviewed May 10, 2026

View reviewed changes

Comment thread src/windows/service/inc/wslservice.idl

Comment thread src/windows/common/WslClient.cpp

This was referenced May 10, 2026

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

Open

WSL 2 should automatically release disk space back to the host OS #4699

Open

Rafa Pradillo (Guayamose) marked this pull request as draft May 10, 2026 03:30

Rafa Pradillo (Guayamose) marked this pull request as ready for review May 10, 2026 11:43

Copilot AI review requested due to automatic review settings May 10, 2026 11:43

Copilot started reviewing on behalf of Rafa Pradillo (Guayamose) May 10, 2026 11:43 View session

Copilot AI reviewed May 10, 2026

View reviewed changes

Comment thread localization/strings/en-US/Resources.resw

Rafa Pradillo (Guayamose) requested a review from Copilot May 10, 2026 12:07

Copilot started reviewing on behalf of Rafa Pradillo (Guayamose) May 10, 2026 12:08 View session

Copilot AI reviewed May 10, 2026

View reviewed changes

Comment thread src/windows/service/exe/LxssUserSession.cpp Outdated

Comment thread test/windows/UnitTests.cpp Outdated

Comment thread test/windows/UnitTests.cpp Outdated

Rafa Pradillo (Guayamose) marked this pull request as draft May 10, 2026 12:44

Rafa Pradillo (Guayamose) marked this pull request as ready for review May 10, 2026 12:46

Copilot AI review requested due to automatic review settings May 10, 2026 12:46

Copilot started reviewing on behalf of Rafa Pradillo (Guayamose) May 10, 2026 12:47 View session

Copilot AI reviewed May 10, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings May 12, 2026 02:49

Copilot started reviewing on behalf of Rafa Pradillo (Guayamose) May 12, 2026 02:50 View session

Copilot AI reviewed May 12, 2026

View reviewed changes

Ben Hillis (benhillis) reviewed May 12, 2026

View reviewed changes

Comment thread src/windows/service/exe/LxssUserSession.cpp Outdated

Ben Hillis (benhillis) requested changes May 12, 2026

View reviewed changes

Comment thread localization/strings/cs-CZ/Resources.resw Outdated

Comment thread src/windows/service/inc/wslservice.idl Outdated

Copilot AI review requested due to automatic review settings May 13, 2026 01:51

Copilot started reviewing on behalf of Rafa Pradillo (Guayamose) May 13, 2026 01:52 View session

Copilot AI reviewed May 13, 2026

View reviewed changes

Comment thread src/windows/service/inc/wslservice.idl

Comment thread src/windows/service/exe/LxssUserSession.cpp

Comment thread localization/strings/en-US/Resources.resw Outdated

Comment thread src/windows/common/WslClient.cpp

Copilot AI review requested due to automatic review settings May 13, 2026 02:15

Copilot started reviewing on behalf of Rafa Pradillo (Guayamose) May 13, 2026 02:16 View session

Rafa Pradillo (Guayamose) added 2 commits August 10, 2026 19:35

Remove redundant compaction sharing violation handling

f61bd10

Remove redundant sparse setup from compact test

906df09

Copilot AI review requested due to automatic review settings August 10, 2026 17:36

Copilot AI reviewed Aug 10, 2026

Merge branch 'master' into draft/vhdx-compact-manual-command

e4b31cd

Copilot AI review requested due to automatic review settings August 10, 2026 17:38

Copilot AI reviewed Aug 10, 2026

Blue (OneBlue) reviewed Aug 10, 2026

View reviewed changes

Comment thread src/windows/service/exe/LxssUserSession.cpp Outdated

Comment thread src/windows/service/exe/LxssUserSession.cpp Outdated

Comment thread test/windows/UnitTests.cpp Outdated

Rafa Pradillo (Guayamose) added 3 commits August 10, 2026 19:58

Simplify VHD compaction logging

427689b

Revert unrelated locked distribution rename

9e07cb3

Remove redundant shutdown from compact test

8d3e799

Copilot AI review requested due to automatic review settings August 10, 2026 17:59

Copilot AI reviewed Aug 10, 2026

Rafa Pradillo (Guayamose) requested a review from Blue (OneBlue) August 10, 2026 18:00

Apply clang-format to compact changes

95c294a

Copilot AI review requested due to automatic review settings August 10, 2026 22:09

Copilot AI reviewed Aug 10, 2026

Merge branch 'master' into draft/vhdx-compact-manual-command

233aa00

Copilot AI review requested due to automatic review settings August 10, 2026 22:49

Copilot AI reviewed Aug 10, 2026

Fix compact command formatting

872f3ff

Copilot AI review requested due to automatic review settings August 11, 2026 08:44

Copilot AI reviewed Aug 11, 2026

Uh oh!

Conversation

Rafa Pradillo (Guayamose) commented May 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary of the Pull Request

PR Checklist

Detailed Description of the Pull Request / Additional comments

Scope

Motivation

Validation

Notes

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Rafa Pradillo (Guayamose) commented May 10, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Rafa Pradillo (Guayamose) commented Aug 10, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Blue (OneBlue) commented Aug 10, 2026

Uh oh!

azure-pipelines Bot commented Aug 10, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Rafa Pradillo (Guayamose) commented Aug 10, 2026

Uh oh!

Blue (OneBlue) commented Aug 10, 2026

Uh oh!

Rafa Pradillo (Guayamose) commented May 10, 2026 •

edited

Loading