WSL systemDistro: The Narrow Contract for a Custom System Image

WSL bundles a system distribution that supports platform-level integration. The current .wslconfig reference exposes systemDistro as an advanced setting whose default is the system distribution bundled with WSL. It accepts an absolute Windows path to a custom system distribution image, with .img and .vhd documented as supported extensions. That is a small contract, not a complete recipe for building a replacement image.

The term “system distribution” can be confused with an ordinary Linux distro such as Ubuntu or Debian. A user distribution is registered by name, owns its Linux root filesystem and packages, and is selected with normal WSL distribution commands. systemDistro instead points WSL at a system-level image used by the platform. The public configuration page does not specify a universal image layout, boot ABI, or compatibility promise. This is not the same as saying no project-specific workflow exists: Microsoft’s WSLg repository documents how to build and select a private WSLg system distribution. That workflow is specific to WSLg and should not be generalized into a supported recipe for arbitrary system images.

Keep the two image roles separate

An ordinary user distribution contains the environment where a developer installs packages, builds projects, and runs Linux applications. It can be listed with wsl.exe –list –verbose, exported, imported, and launched with wsl.exe –distribution <name>. Its per-distribution settings live in /etc/wsl.conf.

The systemDistro image is configured globally in %UserProfile%.wslconfig under [wsl2]. It does not replace the default user distribution or change the name selected by wsl –set-default. It should not be treated as a second registered distro that can be managed using the same lifecycle assumptions. Microsoft documents a bundled system distribution as the default and permits an absolute Windows image path with .img or .vhd extensions; anything beyond those documented facts must be verified for the exact WSL version.

For example, a config fragment might look like:

[wsl2]
systemDistro=C:\\Artifacts\\wsl\\system-image.img

This only demonstrates path syntax. It does not show how to create a valid image, select partitions, provision services, or make a particular image boot correctly. Preserve other [wsl2] settings and re-check the current configuration reference and installed WSL version before applying a global change. Do not copy a random ext4 rootfs, distro VHDX, or WSLg filesystem into this path and assume it is a compatible system image.

Why the public documentation limit matters

Microsoft’s configuration reference names the option and accepted image extensions, but it does not publish a universal custom-system-image authoring guide in the same place. For WSLg specifically, Microsoft’s repository contains build and private-image instructions. Those instructions are useful evidence for that project, but a moving source branch and a WSLg-specific build process are not a universal image ABI or compatibility guarantee for other custom system distributions. .img and .vhd describe file suffixes; they do not specify every image’s partition layout, filesystem, init process, versioning, or mount behavior.

Internal class names and current mount paths can change. If an operational requirement depends on a specific implementation detail, pin it to the exact release and obtain supportability guidance rather than writing an evergreen runbook that assumes the current source tree is a compatibility guarantee.

This is particularly important for WSLg and other platform components. Microsoft’s WSLg repository documents a private system-distro build and selection path for WSLg customization. Use that project-specific procedure when the requirement is specifically to experiment with or customize WSLg; it does not establish compatibility for arbitrary images, versions, or unrelated platform components. For ordinary GUI behavior changes, first use documented WSLg configuration and diagnostics rather than replacing the system image.

Evaluate whether the setting is necessary

Before enabling a custom path, write down the specific limitation in the bundled system image that the change is intended to address. Identify the affected WSL feature, required package or patch, owning team, supported WSL release, update cadence, and rollback action. If the objective can be met inside the user distro, with a supported feature flag, or by using a documented system integration, a custom system image adds unnecessary coupling.

Confirm the change is permitted on the target device and whether its endpoint-management process governs WSL configuration. Do not attempt to bypass a managed configuration. Ask the WSL or endpoint-management owner to confirm whether the setting is allowed and how the image will be serviced.

Keep the image in a Windows path accessible to the same Windows account running WSL. Validate that it exists, that its extension is one Microsoft documents, and that the file is not in a temporary, synchronized, or removable location unless that storage path is explicitly supported. A valid path does not demonstrate a valid image. Record a cryptographic hash, build metadata, source revision, and image-generation procedure for auditability.

Stage the change as a VM-wide intervention

Because systemDistro is under .wslconfig, it is global to the user’s WSL 2 environment. Do not treat it as a per-distro rollout. Plan a test on a disposable Windows profile or machine where no valuable WSL workloads are running. Save the previous configuration and keep an offline copy of the bundled/default state available through the supported rollback procedure.

Before editing, collect:

wsl.exe --version
wsl.exe --status
wsl.exe --list --verbose
Get-Content "$env:USERPROFILE\.wslconfig" -ErrorAction SilentlyContinue
Get-Item "C:\Artifacts\wsl\system-image.img" | Select-Object FullName, Length, LastWriteTimeUtc

Replace the example path with the real file and check that it matches the configured value. Stop WSL workloads cleanly. Applying global settings may require wsl.exe –shutdown, which terminates all running distributions and the utility VM. Then launch one test distro and capture the startup result, relevant WSL logs, and behavior of the specific platform feature the image is intended to change.

Test positive and negative paths. A positive test proves the desired capability still works after startup. A negative test verifies that a missing, inaccessible, or invalid image fails in a recoverable way rather than making every distribution unusable. Do not deliberately point a production device at a corrupt image to discover its failure mode; use a lab host and preserve the default configuration.

Define acceptance around observable platform behavior

The acceptance test must name the capability being changed. For example, if a supported integration depends on a system component, verify the documented end-to-end behavior from a user distro. A VM starting is not proof that the custom image provided the intended feature. Likewise, a GUI application opening is not proof that every WSLg version or distro combination works.

Record WSL version, Windows build, image hash, config file, distro list, launch time, and relevant logs. Repeat the test after a full WSL 2 VM shutdown and a Windows reboot. Test at least two user distributions if they share the VM, since the setting is global. Confirm normal distro registration, startup, Windows interop, file access, and networking as regression checks, but do not interpret those checks as a published image ABI.

When the only available evidence is that a custom image starts, report the result as “startup observed on this build,” not as a general support guarantee. If the feature is a preview or depends on undocumented internals, keep that status visible in change records and limit exposure accordingly.

Rollback and servicing ownership

Rollback should be a straightforward edit: remove the custom systemDistro entry or restore the prior supported value, then restart WSL 2. The bundled distribution is the documented default. Do not remove user distributions, delete their VHDX files, or reinstall WSL simply to revert this setting.

Assign an owner to rebuild and test the image for each WSL release. A system image is coupled to platform behavior; silently carrying it across WSL updates may leave an unsupported combination. Establish a release checklist that compares the current public configuration docs, release notes, and the image’s own source/build metadata. Keep previous tested images immutable until the new one passes acceptance.

If the exact customization has no version-matched official build procedure and an understood compatibility boundary, stop before production rollout. Escalate the requirement through Microsoft’s supported feedback or enterprise support channel, or change the design so it does not depend on an undocumented system image. A configuration option and a project-specific build guide are not enough to establish that arbitrary custom images are supported for every WSL subsystem.

Practical rule

Use systemDistro only when there is a documented, necessary customization and a version-matched image procedure with a rollback owner. Under the general .wslconfig contract, the verified facts are that the default is the bundled system distribution, the custom value is an absolute Windows path, and .img and .vhd extensions are documented. WSLg’s separate build instructions are specific to that project and do not establish a general ABI for arbitrary images. Keeping those boundaries clear prevents a platform-level experiment from being mistaken for an ordinary distro installation.

Related:

Sources: