Command reference for WSL

• 10/05/2021
• 5 minutes to read
• • c
  • m

The basic WSL commands below are listed in a format supported by PowerShell or Windows Command Prompt. To run these commands from a Bash / Linux distribution command line, you must replace wsl with wsl.exe.

Basic commands

The following basic commands are supported after installing WSL.

Install

wsl --install

Install WSL and the Ubuntu distribution of Linux. Learn more.

Install a specific Linux distribution

wsl --install --distribution <Distribution Name>

Designate a distribution of Linux for installation besides the default (Ubuntu) by replacing <Distribution Name> with the name of the distribution. This command can also be entered as: wsl -d <Distribution Name>.

List available Linux distributions

wsl --list --online

See a list of the Linux distributions available through the online store. This command can also be entered as: wsl -l -o.

List installed Linux distributions

wsl --list --verbose

See a list of the Linux distributions installed on your Windows machine, including the state (whether the distribution is running or stopped) and the version of WSL running the distribution (WSL 1 or WSL 2). Comparing WSL 1 and WSL 2. This command can also be entered as: wsl -l -v. Additional options that can be used with the list command include: --all to list all distributions, --running to list only distributions that are currently running, or --quite to only show distribution names.

Set WSL version to 1 or 2

wsl --set-version <distribution name> <versionNumber>

To designate the version of WSL (1 or 2) that a Linux distribution is running on, replace <distribution name> with the name of the distribution and replace <versionNumber> with 1 or 2. Comparing WSL 1 and WSL 2.

Set default WSL version

wsl --set-default-version <Version>

To set a default version of WSL 1 or WSL 2, replacing <Version> with either the number 1 or 2 to represent which version of WSL you would like the installation to default on for new Linux distribution installations. For example, wsl --set-default-version 2. Comparing WSL 1 and WSL 2.

Set default Linux distribution

wsl --set-default <Distribution Name>

To set the default Linux distribution that WSL commands will use to run, replace <Distribution Name> with the name of your preferred Linux distribution.

Run a specific Linux distribution from PowerShell or CMD

wsl --distribution <Distribution Name> --user <User Name>

To run a specific Linux distribution with a specific user, replace <Distribution Name> with the name of your preferred Linux distribution (ie. Debian) and <User Name> with the name of an existing user (ie. root). If the user doesn't exist in the WSL distribution, you will receive an error. To print the current user name, use the command whoami.

Update WSL

wsl --update

Manually update the version of your WSL Linux kernel. You can also use the command: wsl --update rollback to rollback to a previous version of the WSL Linux kernel.

Check WSL status

wsl --status

See general information about your WSL configuration, such as default distribution type, default distribution, and kernel version.

Help command

wsl --help

See a list of options and commands available with WSL.

Home directory

wsl ~

The ~ can be used with wsl to start in the user's home directory. To jump from any directory back to home from within a WSL command prompt, you can use the command: cd ~.

Shutdown

wsl --shutdown

Immediately terminates all running distributions and the WSL 2 lightweight utility virtual machine. This command may be necessary in instances that require you to restart the WSL 2 virtual machine environment, such as changing memory usage limits or making a change to your .wslconfig file.

Terminate

wsl --terminate <Distribution Name>

To terminate the specified distribution, or stop it from running, replace <Distribution Name> with the name of the targeted distribution.

Export a distribution to a TAR file

wsl --export <Distribution Name> <FileName>

Exports the distribution to a tar file. The filename can be - for standard output.

Import a new distribution

wsl --import <Distribution Name> <InstallLocation> <FileName>

Imports the specified tar file as a new distribution. The filename can be - for standard input. The --version option can also be used with this command to designate whether the imported distribution will run on WSL 1 or WSL 2.

Unregister or uninstall a Linux distribution

wsl --unregister <Distribution Name>

Unregister or uninstall the specific distribution by replacing <Distribution Name> with the name of the targeted distribution. This will remove the distribution from WSL and delete all of the associated data. You can also uninstall the Linux distribution app on your Windows machine just like any other store application.

Mount a disk or device

wsl --mount <DiskPath>

Attach and mount a physical disk in all WSL2 distributions by replacing <DiskPath> with the directory\file path where the disk is located. See Mount a Linux disk in WSL 2. Options include:

• wsl --mount --bare: Attach the disk to WSL2, but don't mount it.
• wsl --mount --type <Filesystem>: Filesystem type to use when mounting a disk, if not specified defaults to ext4. This command can also be entered as: wsl --mount -t <Filesystem>.You can detect the filesystem type using the command: blkid <BlockDevice>, for example: blkid <dev/sdb1>.
• wsl --mount --partition <Partition Number>: Index number of the partition to mount, if not specified defaults to the whole disk.
• wsl --mount --options <MountOptions>: There are some filesystem-specific options that can be included when mounting a disk. For example, ext4 mount options like: wsl --mount -o "data-ordered" or wsl --mount -o "data=writeback. However, only filesystem-specific options are supported at this time. Generic options, such as ro, rw, or noatime, are not supported.
• wsl --unmount <DiskPath>: Unmount and detach the disk from all WSL 2 distributions. If the <DiskPath> is not included, this command will unmount and detach ALL mounted disks.

Deprecated WSL commands

wslconfig.exe [Argument] [Options]

bash [Options]

lxrun /[Argument]

These commands were the original wsl syntax for configuring Linux distributions installed with WSL, but have been replaced with the wsl or wsl.exe command syntax.