Build a WSL Compatibility Inventory Before Changing the Platform

“What version of WSL is this?” is not one question. A Windows machine can have a Windows build, a WSL application package, a WSL 2 kernel, one or more Linux distributions, and different per-distribution WSL 1 or WSL 2 modes. A feature may depend on only some of those layers. Reporting one number, such as the kernel release from uname, is not enough to establish whether a WSL setting or command is available.

A compatibility inventory records each layer separately, identifies how it was obtained, and ties a claimed feature to its documented prerequisite. It is useful before an upgrade, when reproducing a bug, and when comparing two machines whose distros look similar but whose platform servicing differs.

Record Windows independently

Start with the Windows edition, version, build, and architecture. winver is a convenient visual check; PowerShell can record machine-readable information:

Get-ComputerInfo |
  Select-Object WindowsProductName, WindowsVersion, OsBuildNumber, OsArchitecture

The exact properties returned can vary across Windows versions and policies, so preserve the raw output if a support report needs to be reproducible. The WSL manual installation and feature documentation often express prerequisites as Windows builds or releases. Check the current official documentation for the specific feature; do not infer support from the fact that some other WSL feature works.

Also record whether the machine is Windows client or Windows Server and whether it is managed by policy. Edition, servicing channel, virtualization configuration, and organizational restrictions can matter independently of the build number.

Identify the WSL package and kernel layers

From PowerShell, collect both status and component versions:

wsl.exe --status
wsl.exe --version
wsl.exe --help

wsl –status reports general configuration, including the default distribution type and kernel version. wsl –version reports WSL component version information when supported by the installed servicing path. Older inbox installations can reject –version; that result is evidence of a different interface or package state, not proof that WSL is absent.

The kernel reported by wsl –status and uname -r inside a WSL 2 guest are related observations, but they answer different questions. The Windows-side command gives the WSL-managed kernel version; uname reports the kernel actually visible in the current Linux environment. A custom kernel configured globally, a running VM that has not been restarted, or a WSL 1 distro can make the relationship differ from an operator’s assumption.

Do not treat the WSL package version as the Linux distribution release. WSL is the platform integration layer. A distribution has its own package repositories, userspace libraries, init configuration, and security updates.

Inventory each distribution separately

Use WSL’s list commands and inspect each Linux environment directly:

wsl.exe --list --verbose
wsl.exe --list --quiet
wsl.exe --distribution Ubuntu-24.04 --exec cat /etc/os-release
wsl.exe --distribution Ubuntu-24.04 --exec uname -r

The verbose list includes the registered name, running state, and WSL version for each distro. /etc/os-release identifies the userspace distribution and release. The guest architecture can be collected with uname -m; on Windows, compare that with OsArchitecture and any emulation or ARM-specific requirement before choosing a package.

An imported distro may have a registration name that does not resemble its operating system release. A package may also use an architecture-specific repository or binary. Capture all three facts: registered WSL name, userspace identity, and guest architecture. When there are multiple distros, do not run a command against the mutable default distro in an evidence bundle; pass –distribution explicitly.

Convert a feature requirement into a gate table

For each feature under investigation, record its controlling layer and prerequisite. For example, a global VM option may require WSL 2 and a compatible WSL configuration parser; systemd depends on the WSL platform version as well as the distro having the necessary service-manager packages; a Windows Terminal property depends on Terminal itself rather than the Linux kernel. The current documentation, not a memory of an old release note, is authoritative.

Use a small table in an incident ticket:

Layer	Evidence	Question answered
Windows	Edition, build, architecture	Does this OS build meet the feature’s host prerequisite?
WSL package	`wsl –version`, or an explicit unsupported-command result	Which WSL component servicing path is installed?
WSL configuration	Redacted `.wslconfig` and distro `wsl.conf`	Is the feature enabled at the scope it expects?
Distro	`/etc/os-release`, package versions	Does the guest userspace provide required binaries or libraries?
Kernel	`wsl –status`, `uname -r`, relevant config	Is the running guest kernel the expected one?
Architecture	Windows and guest architecture	Are kernel modules, packages, or binaries built for the right target?

This prevents common false diagnoses. Updating Ubuntu packages does not necessarily update the WSL application. Updating WSL does not necessarily upgrade the distro. wsl –update does not prove that the intended distro restarted and began running a new kernel. A reboot may update Windows while leaving a policy-controlled package source unchanged.

Compare versions without exposing machine secrets

For a support case, make a plain text inventory with machine identifiers removed:

Get-ComputerInfo |
  Select-Object WindowsProductName, WindowsVersion, OsBuildNumber, OsArchitecture |
  Format-List
wsl.exe --status
wsl.exe --version
wsl.exe --list --verbose

In each relevant distribution:

cat /etc/os-release
uname -a
uname -m
printf 'WSL_DISTRO_NAME=%s\n' "$WSL_DISTRO_NAME"

Review output before sharing it. Avoid attaching environment dumps that could expose usernames, paths, proxy settings, environment credentials, or unrelated service details. The goal is a minimal compatibility record, not indiscriminate collection.

For a feature gate, add a short evidence row rather than only pasting version output. State the documented minimum, the machine’s observed value, the command or UI that produced it, and the result of the feature’s own functional test. If a Microsoft article says that a property is available only on a certain Windows release or WSL package, cite that section and use the matching host layer as the comparison. If no minimum is published, say that the documentation does not specify one instead of deriving a minimum from the first release note you can find.

Preserve a useful before-and-after record

Version inventory is most valuable when the same commands are captured before and after a deliberate change. Keep timestamp, distro name, update method, restart action, and exact tested workload next to each snapshot. That makes it possible to distinguish an update that downloaded successfully from an update that changed the running environment.

When two machines differ, compare the layer that owns the behavior. A package installed in the Linux distro is not evidence about a WSL Windows component; a GUI preference in Windows Terminal is not evidence about the guest kernel. This ownership model shortens incident triage because each mismatch points to one responsible update path.

Change one layer at a time

If a feature is missing, first compare its prerequisite against the inventory. If the platform update is justified, record the current package path and version, update with the documented mechanism, then shut down the relevant WSL instance when the update or configuration requires a restart. Re-run the same inventory and acceptance command. Do not change the Windows build, WSL package, kernel selection, and distro release in one maintenance window unless a dependency explicitly requires a coordinated sequence.

For an older inbox installation, wsl –version may not exist. Check the Windows version and the current Microsoft installation/update guidance; do not copy a command from a newer machine and assume it is universal. For an organization-managed system, consult the controlling policy before attempting Store or web-download updates.

Acceptance criteria

A useful WSL compatibility record is complete when it states: Windows edition/build/architecture; WSL package version or the exact reason that command is unsupported; WSL kernel and default mode; every target distro’s registered name, userspace release, and WSL version; relevant configuration with secrets removed; and the exact source document defining the feature prerequisite.

After a change, prove the intended feature in the intended distro. A version string is necessary evidence, not a substitute for a functional test. Keep the before-and-after inventory so a later regression can be tied to one changed layer rather than a vague statement that “WSL was updated.”

Related:

Sources: