Basic commands for WSL

Posted on

The 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 them with wsl.exe. For a complete list of commands, run. wsl --help.

Install

PowerShellCopy

wsl --install

Copy

Install WSL and the default Ubuntu distribution of Linux. You can also use this command to install additional Linux distributions by running wsl --install <Distribution Name>. For a good list of distribution names, run. wsl --list --online.

Options include:

  • --distribution: Specify the Linux distribution to install. You can find available distributions by running. wsl --list --online.
  • --no-launch: Install the Linux distribution but do not launch it automatically.
  • --web-download: Install from an online source rather than using the Microsoft Store.

When WSL is not installed, options include:

  • --inbox: Install WSL using the Windows component instead of using the Microsoft Store. (WSL updates will be received via Windows updates rather than pushed out as available via the store).
  • --enable-wsl1: Enables WSL 1 while installing the Microsoft Store version of WSL by enabling the “Windows Subsystem for Linux” optional component.
  • --no-distribution: Do not install a distribution when installing WSL.

List available Linux distributions

PowerShellCopy

wsl --list --online

Copy

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.

PowerShellCopy

wsl --list --verbose

Copy

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). This command can also be entered as: wsl -l -v. Additional options that can be used with the list command include the following: --all to list all distributions, --running to list only distributions that are currently running, or --quiet to only show distribution names.

Set the WSL version to 1 or 2

PowerShellCopy

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

Copy

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> it is with 1 or 2. 

Set default WSL version.

PowerShellCopy

wsl --set-default-version <Version>

Copy

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

Set default Linux distribution.

PowerShellCopy

wsl --set-default <Distribution Name>

Copy

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

Change directory to home

PowerShellCopy

wsl ~

Copy

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 ~.

Run a specific Linux distribution from PowerShell or CMD

PowerShellCopy

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

Copy

To run a particular Linux distribution with a particular user, replace <Distribution Name> it with the name of your preferred Linux distribution (i.e., Debian) and <User Name> with the name of an existing user (i.e., root). You will receive an error if the user doesn’t exist in the WSL distribution. To print the current user name, use the command whoami.

Update WSL

PowerShellCopy

wsl --update

Copy

Update your WSL version to the latest version. Options include:

  • --web-download: Download the newest update from GitHub rather than the Microsoft Store.

Check WSL status

PowerShellCopy

wsl --status

Copy

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

Check WSL version

PowerShellCopy

wsl --version

Copy

Check the version information about WSL and its components.

Help command

PowerShellCopy

wsl --help

Copy

See a list of options and commands available with WSL.

Run as a specific user

PowerShellCopy

wsl -u <Username>`, `wsl --user <Username>

Copy

To run WSL as a specified user, replace <Username> it with the name of a user that exists in the WSL distribution.

Change the default user for a distribution

PowerShellCopy

<DistributionName> config --default-user <Username>

Copy

Change the default user for your distribution log-in. The user must already exist inside the distribution to become the default user.

For example: ubuntu config --default-user johndoe would change the default user for the Ubuntu distribution to the “Johndoe” user.

Note

If you are having trouble figuring out the name of your distribution, use the command. wsl -l.

Warning

This command will not work for imported distributions because these distributions do not have an executable launcher. You can instead change the default user for imported distributions using the /etc/wsl.conf file. 

Shutdown

PowerShellCopy

wsl --shutdown

Copy

Immediately terminates all running distributions and the WSL 2 lightweight utility virtual machine. 

Terminate

PowerShellCopy

wsl --terminate <Distribution Name>

Copy

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

Import and export a distribution

PowerShellCopy

wsl --export <Distribution Name> <FileName>

Copy

PowerShellCopy

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

Copy

Imports and exports the specified tar file as a new distribution. The filename can be – for standard input. Options include:

  • --vhd: Specifies the import/export distribution should be a .vhdx file instead of a tar file
  • --version: For import only, specifies whether to import the distribution as a WSL 1 or WSL 2 distribution

Import a distribution in place.

PowerShellCopy

wsl --import-in-place <Distribution Name> <FileName>

Copy

Imports the specified .vhdx file as a new distribution. The virtual hard disk must be formatted in the ext4 filesystem type.

Unregister or uninstall a Linux distribution

While Linux distributions can be installed through the Microsoft Store, they can’t be uninstalled through the store.

To unregister and uninstall a WSL distribution:

PowerShellCopy

wsl --unregister <DistributionName>

Copy

Replacing <DistributionName> with the name of your targeted Linux distribution will unregister that distribution from WSL so it can be reinstalled or cleaned up. Caution: Once unregistered, all data, settings, and software associated with that distribution will be permanently lost. Reinstalling from the store will install a clean copy of the distribution. For example, wsl --unregister Ubuntu it would remove Ubuntu from the distributions available in WSL. Running wsl --list will reveal that it is no longer listed.

You can also uninstall the Linux distribution app on your Windows machine like any other storage application. To reinstall, find the distribution in the Microsoft Store and select “Launch.”

Mount a disk or device.

PowerShellCopy

wsl --mount <DiskPath>

Copy

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

  • --vhd: Specifies that <Disk> refers to a virtual hard disk.
  • --name: Mount the disk using a custom name for the mount point
  • --bare: Attach the disk to WSL2, but don’t mount it.
  • --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>.
  • --partition <Partition Number>: Index number of the partition to mount, if not specified, defaults to the whole disk.
  • --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.

Note

If you’re running a 32-bit process in order to access wsl.exe (a 64-bit tool), you may need to run the command in the following manner: C:\Windows\Sysnative\wsl.exe --command.

Unmount disks

PowerShellCopy

wsl --unmount <DiskPath>

Copy

Unmount a disk given at the disk path; if no disk path is given, then this command will unmount and detach ALL mounted disks.

Deprecated WSL commands

PowerShellCopy

wslconfig.exe [Argument] [Options]

Copy

PowerShellCopy

bash [Options]

Copy

PowerShellCopy

lxrun /[Argument]

Copy

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.