The essentials

Quick reference

One focused task per row. Jump to the related section for complete, working examples.

UseSyntaxExamples
Show WSL statuswsl.exe --statusView examples
Show component versionswsl.exe --versionView examples
List installed distributionswsl.exe --list --verboseView examples
List available distributionswsl.exe --list --onlineView examples
Install without launchingwsl.exe --install --distribution Debian --no-launchView examples
Set default distributionwsl.exe --set-default DebianView examples
Default new installs to WSL 2wsl.exe --set-default-version 2View examples
Convert a distributionwsl.exe --set-version Debian 2View examples
Run in a named distributionwsl.exe --distribution Debian --exec bash -lc ` 'id && uname -a'View examples
Run as an explicit userwsl.exe --distribution Debian --user dev --exec whoamiView examples
Update WSL runtimewsl.exe --updateView examples
Terminate one distributionwsl.exe --terminate DebianView examples
Shut down all WSL instanceswsl.exe --shutdownView examples
Export distribution to TARwsl.exe --export Debian 'D:\WSL-Backups\Debian.tar'View examples
Hash exported backupGet-FileHash -LiteralPath 'D:\WSL-Backups\Debian.tar' ` -Algorithm SHA256View examples
Import under a test namewsl.exe --import Debian-Restore 'D:\WSL\Debian-Restore' ` 'D:\WSL-Backups\Debian.tar' --version 2View examples
Unregister a distributionwsl.exe --unregister DebianView examples

WSL has two management layers: the Windows-side WSL runtime and one or more Linux distributions with independent users, packages, services, and filesystems. Name the target distribution explicitly in automation, keep Linux projects in the Linux filesystem when Linux tools own the workload, quiesce applications before export or conversion, and verify a restorable backup before unregistering anything.

Step by step

Detailed examples

01

Inventory runtime and distribution state before choosing a target

wsl.exe --version describes the Windows-side runtime; --list --verbose describes each registered distribution and whether it uses WSL 1 or WSL 2. Store the exact registered name because display names, Store packages, and imported distribution names are not interchangeable. Most inventory and execution commands do not require elevation, while initial feature enablement, some installation paths, and physical disk attachment do.

Capture the Windows-side WSL baseline
wsl.exe --status
wsl.exe --version
wsl.exe --list --verbose
wsl.exe --list --running
Get-ComputerInfo | Select-Object WindowsProductName, WindowsVersion, OsBuildNumber, OsArchitecture
Back to quick reference ↑
02

Separate feature installation, distribution installation, and defaults

On supported Windows 10 and Windows 11 builds, wsl.exe --install can enable required features and install a distribution; run the initial setup from an elevated PowerShell session and expect a Windows restart. --no-launch defers creation of the Linux user. Setting a default distribution changes unqualified command routing, and setting a default version affects only future installations—not existing distributions. Enterprise Store, virtualization, and optional-feature policy can block installation.

Discover, then install one named distribution
wsl.exe --list --online
# From an elevated console after confirming virtualization, policy, disk, and restart impact:
# wsl.exe --install --distribution Debian --no-launch
# Restart Windows if requested, then launch Debian to create its Linux user.
# After validation, choose the unqualified-command target:
# wsl.exe --set-default Debian
Back to quick reference ↑
03

Choose WSL 1 or WSL 2 for the workload, not by habit

WSL 2 is the current default and provides a real Linux kernel, broad system-call compatibility, systemd support, and strong performance when Linux tools operate on files in the Linux filesystem. WSL 1 can be useful for some cross-OS filesystem workloads or environments without WSL 2 virtualization support. Conversion rewrites storage, can take a long time, needs free disk space, stops the distribution, and can fail; Microsoft recommends backing up large projects first. A default-version change does not convert existing instances.

Back up before an explicit architecture conversion
wsl.exe --list --verbose
wsl.exe --terminate Debian
wsl.exe --export Debian 'D:\WSL-Backups\Debian-before-conversion.tar'
Get-FileHash 'D:\WSL-Backups\Debian-before-conversion.tar' -Algorithm SHA256
# Choose the architecture for future installations independently:
# wsl.exe --set-default-version 2
# After checking free disk space and testing restore:
# wsl.exe --set-version Debian 2
# Re-run --list --verbose and application smoke tests after conversion.
Back to quick reference ↑
04

Make distribution, user, shell, path, and quoting boundaries explicit

A Windows process invokes wsl.exe, which selects a distribution and Linux user before starting a Linux executable. Use -- to separate WSL options from the Linux command and specify --distribution in automation. PowerShell expands its own variables and quoting before Linux sees arguments; bash -lc adds another parsing layer, so avoid interpolating untrusted strings. Running as root bypasses Linux ownership controls and should not be a convenience default.

Target a distribution and ordinary Linux user
wsl.exe --distribution Debian --user dev --exec whoami
wsl.exe --distribution Debian --user dev --exec pwd
wsl.exe --distribution Debian --user dev --exec bash -lc 'printf "user=%s\n" "$USER"; uname -r'
# Pass fixed arguments directly when possible; do not concatenate untrusted input into bash -lc.
Back to quick reference ↑
05

Update and stop WSL without confusing runtime and distro maintenance

wsl.exe --update updates the WSL runtime and kernel, not apt, dnf, or other packages inside distributions. Coordinate both maintenance streams. --terminate immediately ends one distribution; --shutdown ends all distributions and the WSL 2 utility VM, which can interrupt shells, editors, databases, containers, and writes. Quiesce applications and sync important data first. A Windows reboot can also interrupt WSL and may be required after feature installation.

Inspect workloads before a controlled runtime restart
wsl.exe --list --running
wsl.exe --distribution Debian --exec bash -lc 'ps -eo pid,user,comm --sort=comm | head -30'
# Stop databases, containers, editors, and other writers inside each distribution first.
# wsl.exe --update
# wsl.exe --terminate Debian
# wsl.exe --shutdown
wsl.exe --status
wsl.exe --version
Back to quick reference ↑
06

Prove exports by restoring under a different name

Export captures a distribution snapshot but not every Windows-side dependency, secret, external mount, Store registration detail, or application-consistent database state. Stop application writers and terminate the distribution before export. Store backups outside the distribution, protect their Linux secrets and private keys, record a SHA-256 digest, and import under a new name and directory for restore testing. An imported distribution may need /etc/wsl.conf to define its default user because Store launcher configuration does not apply.

Create and test a recoverable TAR export
$backup = 'D:\WSL-Backups\Debian.tar'
# Quiesce application writers inside Debian before termination.
wsl.exe --terminate Debian
wsl.exe --export Debian $backup
Get-Item -LiteralPath $backup | Select-Object FullName, Length, LastWriteTimeUtc
Get-FileHash -LiteralPath $backup -Algorithm SHA256
# Restore to a distinct name and path; never overwrite the source during the test.
# wsl.exe --import Debian-Restore 'D:\WSL\Debian-Restore' $backup --version 2
# wsl.exe --distribution Debian-Restore --exec bash -lc 'id; df -h /; test -d /home'
Back to quick reference ↑
07

Treat unregister as irreversible data deletion

wsl.exe --unregister permanently removes the named distribution, including its Linux filesystem, packages, configuration, and user data. Reinstalling the Store app creates a clean distribution and does not recover that data. Resolve the exact name, stop it, export it, hash the export, restore-test under another name, and obtain approval before unregistering. Uninstalling the distribution app and unregistering its data are related but distinct actions; do not assume an application uninstall is a backup.

Build evidence before an approved unregister
$target = 'Debian'
wsl.exe --list --verbose
wsl.exe --distribution $target --exec bash -lc 'hostname; id; df -h /'
Get-Item 'D:\WSL-Backups\Debian.tar' | Select-Object FullName, Length, LastWriteTimeUtc
Get-FileHash 'D:\WSL-Backups\Debian.tar' -Algorithm SHA256
# Confirm the separate restore opens and required data exists. Then, with explicit approval:
# wsl.exe --unregister $target
# This command permanently deletes the registered distribution.
Back to quick reference ↑

Keep exploring

More Windows cheat sheets

Sources and further reading

References

Authoritative documentation used to verify and expand this cheat sheet.

  1. MicrosoftBasic commands for WSLlearn.microsoft.com
  2. MicrosoftInstall WSLlearn.microsoft.com
  3. MicrosoftComparing WSL Versionslearn.microsoft.com
  4. MicrosoftAdvanced settings configuration in WSLlearn.microsoft.com
  5. MicrosoftFrequently Asked Questions about Windows Subsystem for Linuxlearn.microsoft.com

Help us improve

Found a typo or missing example?

Tell us what would make this cheat sheet clearer, more complete, or more useful.

Share feedback