12 Essential WSL Commands for Windows 10 and 11: Setup, Backups and Troubleshooting

H2S Media’s guide to 12 essential WSL commands provides a practical checklist. The commands below retain that everyday focus, with additional safeguards for backups, disk operations, and network access—and one important distinction throughout: the WSL package version and a distribution’s WSL 1/WSL 2 setting are different things. Microsoft exposes them through separate inspection commands.

Before you start​

Run these examples in PowerShell, unless a block is explicitly identified as Linux configuration. Most also work in Command Prompt. Inside Linux, use wsl.exe instead of wsl when invoking the Windows management tool. Replace example distribution names, usernames, and directories with your own; wsl --help shows which options your installation supports.

For the streamlined installation procedure, Microsoft specifies Windows 11 or Windows 10 version 2004, build 19041 or later. First-time installation requires an administrator terminal and a Windows restart. Those are installation requirements, not a statement about the support lifecycle of every qualifying Windows release.

The 12 everyday WSL commands​

1. List distributions: wsl -l -v​

wsl -l -v

This identifies installed distributions, their running or stopped state, and their WSL architecture version. Use the displayed registered name when targeting a distribution. For scripts, wsl -l -q returns names only; wsl -l --running filters active environments.

2. Install WSL: wsl --install​

From an administrator PowerShell window:

wsl --install

Microsoft’s default installation includes Ubuntu. To select another distribution:

wsl --list --online
wsl --install -d Debian

Restart when prompted, then finish the distribution’s initial setup. Microsoft also documents --no-launch to suppress automatic launch and --no-distribution to install WSL without a Linux distribution.

3. Choose an environment: wsl -d​

wsl -d Debian

Use an explicit distribution name when maintaining multiple environments. You can also execute a command without entering an interactive session:

wsl -d Debian cat /etc/os-release

The distribution selector is documented in Microsoft’s WSL command help.

4. Start at home: wsl ~​

wsl ~

This opens the Linux user’s home directory rather than inheriting the Windows terminal’s current directory. Microsoft documents both home-directory launching and the normal working-directory inheritance behavior.

There is a practical performance reason to care: Microsoft recommends keeping projects in the Linux filesystem when using Linux command-line tools, rather than working across the Windows/Linux filesystem boundary unnecessarily. A Linux-based build belongs naturally under a path such as /home/dev/projects, not automatically under /mnt/c.

5. Select a working directory: wsl --cd​

wsl -d Ubuntu --cd /home/dev/projects/api
wsl -d Ubuntu --cd "C:\Users\dev\source\website"

Microsoft’s command help specifies three forms: a standalone ~, an absolute Linux path beginning with /, or an absolute Windows path. Use explicit paths in automation rather than assuming ~/projects receives shell-style expansion. The destination must already exist.

6. Execute a Linux program: wsl --exec​

wsl -d Ubuntu --exec uname -a
wsl -d Ubuntu --exec python3 --version

--exec, shortened to -e, bypasses the default Linux shell. When you need Linux shell syntax, invoke the shell explicitly:

wsl -d Ubuntu -e bash -c 'ls *.json | wc -l'

Microsoft’s help defines the execution distinction. Keeping the pipeline inside the quoted Bash command also avoids accidentally making it a PowerShell pipeline.

7. Select a Linux user: wsl --user​

wsl -d Ubuntu -u root

The selected user must exist. H2S Media also describes the password-recovery pattern:

wsl -d Ubuntu -u root passwd dev

Replace dev with the existing account whose Linux password needs resetting. Microsoft documents the distribution and user selectors; its interoperability guidance also makes clear that Windows-side permissions remain tied to the calling Windows process. Linux root is not a shortcut to Windows administrator privileges.

8. Choose the default distribution: wsl --set-default​

wsl --set-default Ubuntu

Commands without an explicit distribution then target that environment. For repeatable scripts, specifying -d remains the clearer choice.

9. Inspect configuration: wsl --status​

wsl --status
wsl --version

These answer different questions: --status reports configuration; --version reports WSL component versions. Neither should be confused with the per-distribution architecture shown by wsl -l -v.

10. Update WSL: wsl --update​

wsl --update

If the Microsoft Store delivery route fails, Microsoft documents:

wsl --update --web-download

That uses GitHub instead. It updates WSL, not the packages installed inside Ubuntu. H2S Media separately identifies Ubuntu’s package-maintenance command, run inside Ubuntu:

sudo apt update && sudo apt upgrade

Use the package manager appropriate to your distribution; Microsoft’s interoperability examples likewise treat Linux package updates as a separate operation.

11. Stop everything: wsl --shutdown​

wsl --shutdown

This stops all running distributions and the WSL 2 utility VM. Save Linux work and stop important services first. Microsoft identifies shutdown as a way to apply VM configuration changes—not merely as a way to close a terminal.

For example, the following belongs in %UserProfile%\.wslconfig:

[wsl2]
memory=8GB

It sets a WSL 2 VM memory limit across distributions, not an individual Ubuntu allowance. Choose a limit appropriate to your machine. Microsoft distinguishes this global configuration from per-distribution settings in /etc/wsl.conf.

12. Stop one distribution: wsl --terminate​

wsl --terminate Ubuntu

Use targeted termination when other distributions should remain available. Microsoft also documents it as a way to stop a distribution immediately before restarting it to apply local configuration changes.

The everyday rule: inspect first, target explicitly, and reserve a full shutdown for changes or failures that warrant affecting every environment.

Six advanced commands for recovery and storage​

Export a backup​

H2S Media’s backup pattern uses a TAR export:

wsl --export Ubuntu "D:\wsl-backups\ubuntu-pre-upgrade.tar"

Create the destination directory beforehand and check available space. For a cleaner recovery point, stop databases and development servers normally before exporting. Microsoft documents TAR exports and the WSL 2-only --vhd alternative.

Import a recoverable copy​

wsl --import Ubuntu-Restore "D:\WSL\Ubuntu-Restore" "D:\wsl-backups\ubuntu-pre-upgrade.tar" --version 2

Use a new registration name and a separate installation directory. Microsoft’s import documentation confirms the name, installation-location, and archive arguments.

After import, verify the environment rather than treating a successful command as proof that every application is healthy. If it launches as root, configure an existing normal user in /etc/wsl.conf, preserving other settings:

[user]
default=dev

Terminate and reopen that distribution to apply the change. Microsoft documents the default-user setting and the restart requirement.

Convert an existing distribution​

wsl --set-version Ubuntu 2

Microsoft warns that conversion can take time and fail. Back up first.

Set the architecture for future installations​

wsl --set-default-version 2

This affects new distributions; it does not convert existing ones.

Mount a physical Linux disk​

This is an administrator operation, not routine project navigation. Microsoft requires Windows 11 or the Microsoft Store version of WSL and warns that mounting attaches the entire disk, even when requesting one partition. The Windows installation disk cannot be mounted this way. USB flash drives and SD-card readers are not supported by this command.

H2S Media recommends identifying disks first:

Get-CimInstance -Query "SELECT * from Win32_DiskDrive"

Only after confirming the correct device should you adapt this example:

wsl --mount \\.\PHYSICALDRIVE2 --partition 1 --type ext4
wsl --unmount \\.\PHYSICALDRIVE2

Do not assume PHYSICALDRIVE2 is your intended disk. Microsoft documents partition selection and detachment; omitting the disk from --unmount detaches all attached disks.

Unregister an unwanted distribution​

wsl --unregister Ubuntu-Restore

This permanently removes that distribution’s associated data, settings, and software. Export anything valuable first and verify the target name. This is deletion, not a reset button with an undo arrow.

Move a distribution without confusing relocation with cleanup​

For installations whose local help includes the option, Microsoft’s WSL command strings document:

wsl --shutdown
wsl --manage Ubuntu --move "D:\WSL\Ubuntu"

Check wsl --help for support before proceeding. Relocation addresses where the distribution lives; it is not itself a filesystem-cleanup procedure.

Where that option is unavailable, H2S Media describes export and import as the alternative. Import under a new name, verify your files and tools, and only then consider unregistering the original. Microsoft’s import syntax permits choosing the new installation location.

Avoid casually enabling sparse-disk settings as a universal space-recovery fix. Microsoft lists sparseVhd as experimental and disabled by default. A storage experiment is no substitute for a verified backup.

Find the WSL IP address—and understand its limits​

wsl -d Ubuntu hostname -I

Use capital I. Microsoft documents this as a way to obtain the WSL 2 environment’s address. But an address alone does not make a development server accessible from another device.

Microsoft’s networking guidance separates three cases:

• Windows to Linux: a WSL-hosted service can normally be reached through Windows localhost.
• Another device to WSL under NAT: additional forwarding and firewall configuration may be needed.
• Mirrored networking: connectivity differs from NAT, including host/guest localhost access.

A server bound only to 127.0.0.1 may also reject LAN access. Binding more broadly can enable access, but increases exposure; restrict access to the intended network and service rather than disabling the firewall.

Troubleshoot in a deliberate order​

Microsoft’s troubleshooting guidance emphasizes collecting the architecture, kernel, and distribution details. Start with evidence, not a reinstall.

These are diagnostic branches, not guaranteed diagnoses; Microsoft documents multiple causes for these failures.

For a normal development session, the sensible sequence is simple: identify the environment, enter the intended project directory, run tools explicitly, and take a backup before disruptive changes. The commands are short. Knowing which environment they affect—and which ones can destroy it—is the part worth remembering.