|
| 1 | +--- |
| 2 | +title: Basic commands for WSL |
| 3 | +description: Reference for the basic commands included with Windows Subsystem for Linux (WSL). |
| 4 | +ms.date: 12/01/2025 |
| 5 | +ms.topic: article |
| 6 | +--- |
| 7 | + |
| 8 | +# Basic commands for WSL |
| 9 | + |
| 10 | +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` with `wsl.exe`. For a full list of commands, run `wsl --help`. If you have not yet done so, we recommend [updating to the version of WSL installed from Microsoft Store](https://apps.microsoft.com/detail/9P9TQF7MRM4R) in order to receive WSL updates as soon as they are available. ([Learn more about installing WSL via Microsoft Store.](https://devblogs.microsoft.com/commandline/the-windows-subsystem-for-linux-in-the-microsoft-store-is-now-generally-available-on-windows-10-and-11/)). |
| 11 | + |
| 12 | +## Install |
| 13 | + |
| 14 | +```powershell |
| 15 | +wsl --install |
| 16 | +``` |
| 17 | + |
| 18 | +Install WSL and the default Ubuntu distribution of Linux. [Learn more](./install.md). You can also use this command to install additional Linux distributions by running `wsl --install <Distribution Name>`. For a valid list of distribution names, run `wsl --list --online`. |
| 19 | + |
| 20 | +Options include: |
| 21 | + |
| 22 | +- `--distribution`: Specify the Linux distribution to install. You can find available distributions by running `wsl --list --online`. |
| 23 | +- `--no-launch`: Install the Linux distribution but do not launch it automatically. |
| 24 | +- `--web-download`: Install from an online source rather than using the Microsoft Store. |
| 25 | +- `--location`: Specify which folder you would like to install the WSL distribution to. |
| 26 | + |
| 27 | +When WSL is not installed options include: |
| 28 | + |
| 29 | +- `--inbox`: Installs 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).* |
| 30 | +- `--enable-wsl1`: Enables WSL 1 during the install of the Microsoft Store version of WSL by also enabling the "Windows Subsystem for Linux" optional component. |
| 31 | +- `--no-distribution`: Do not install a distribution when installing WSL. |
| 32 | + |
| 33 | +> [!NOTE] |
| 34 | +> If you run WSL on Windows 10 or an older version, you may need to include the `-d` flag with the `--install` command to specify a distribution: `wsl --install -d <distribution name>`. |
| 35 | +
|
| 36 | +## List available Linux distributions |
| 37 | + |
| 38 | +```powershell |
| 39 | +wsl --list --online |
| 40 | +``` |
| 41 | + |
| 42 | +See a list of the Linux distributions available through the online store. This command can also be entered as: `wsl -l -o`. |
| 43 | + |
| 44 | +## List installed Linux distributions |
| 45 | + |
| 46 | +```powershell |
| 47 | +wsl --list --verbose |
| 48 | +``` |
| 49 | + |
| 50 | +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](./compare-versions.md). 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 `--quiet` to only show distribution names. |
| 51 | + |
| 52 | +## Set WSL version to 1 or 2 |
| 53 | + |
| 54 | +```powershell |
| 55 | +wsl --set-version <distribution name> <versionNumber> |
| 56 | +``` |
| 57 | + |
| 58 | +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](./compare-versions.md). WSL 2 is only available in Windows 11 or Windows 10, Version 1903, Build 18362 or later. |
| 59 | + |
| 60 | +> [!WARNING] |
| 61 | +> Switching between WSL 1 and WSL 2 can be time-consuming and result in failures due to the differences between the two architectures. For distributions with large projects, we recommend backing up files before attempting a conversion. |
| 62 | +
|
| 63 | +## Set default WSL version |
| 64 | + |
| 65 | +```powershell |
| 66 | +wsl --set-default-version <Version> |
| 67 | +``` |
| 68 | + |
| 69 | +To set a default version of WSL 1 or WSL 2, replace `<Version>` with either the number 1 or 2. For example, `wsl --set-default-version 2`. The number represents the version of WSL to default to for new Linux distribution installations. [Comparing WSL 1 and WSL 2](./compare-versions.md). WSL 2 is only available in Windows 11 or Windows 10, Version 1903, Build 18362 or later. |
| 70 | + |
| 71 | +## Set default Linux distribution |
| 72 | + |
| 73 | +```powershell |
| 74 | +wsl --set-default <Distribution Name> |
| 75 | +``` |
| 76 | + |
| 77 | +To set the default Linux distribution that WSL commands will use to run, replace `<Distribution Name>` with the name of your preferred Linux distribution. |
| 78 | + |
| 79 | +## Start WSL in user home directory |
| 80 | + |
| 81 | +```powershell |
| 82 | +wsl ~ |
| 83 | +``` |
| 84 | + |
| 85 | +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 ~`. |
| 86 | + |
| 87 | +## Run a specific Linux distribution from PowerShell or CMD |
| 88 | + |
| 89 | +```powershell |
| 90 | +wsl --distribution <Distribution Name> --user <User Name> |
| 91 | +``` |
| 92 | + |
| 93 | +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`. |
| 94 | + |
| 95 | +## Update WSL |
| 96 | + |
| 97 | +```powershell |
| 98 | +wsl --update |
| 99 | +``` |
| 100 | + |
| 101 | +Update your WSL version to the latest version. Options include: |
| 102 | + |
| 103 | +- `--web-download`: Download the latest update from the GitHub rather than the Microsoft Store. |
| 104 | + |
| 105 | +## Check WSL status |
| 106 | + |
| 107 | +```powershell |
| 108 | +wsl --status |
| 109 | +``` |
| 110 | + |
| 111 | +See general information about your WSL configuration, such as default distribution type, default distribution, and kernel version. |
| 112 | + |
| 113 | +## Check WSL version |
| 114 | + |
| 115 | +```powershell |
| 116 | +wsl --version |
| 117 | +``` |
| 118 | + |
| 119 | +Check the version information about WSL and its components. |
| 120 | + |
| 121 | +## Help command |
| 122 | + |
| 123 | +```powershell |
| 124 | +wsl --help |
| 125 | +``` |
| 126 | + |
| 127 | +See a list of options and commands available with WSL. |
| 128 | + |
| 129 | +## Run as a specific user |
| 130 | + |
| 131 | +```powershell |
| 132 | +wsl --user <Username> |
| 133 | +``` |
| 134 | + |
| 135 | +To run WSL as a specified user, replace `<Username>` with the name of a user that exists in the WSL distribution. |
| 136 | + |
| 137 | +## Change the default user for a distribution |
| 138 | + |
| 139 | +```powershell |
| 140 | +<DistributionName> config --default-user <Username> |
| 141 | +``` |
| 142 | + |
| 143 | +Change the default user for your distribution log-in. The user has to already exist inside the distribution in order to become the default user. |
| 144 | + |
| 145 | +For example: |
| 146 | +`ubuntu config --default-user johndoe` would change the default user for the Ubuntu distribution to the "johndoe" user. |
| 147 | + |
| 148 | +> [!NOTE] |
| 149 | +> If you are having trouble figuring out the name of your distribution, use the command `wsl -l`. |
| 150 | +
|
| 151 | +> [!WARNING] |
| 152 | +> 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. See the Automount options in the [Advanced Settings Configuration](./wsl-config.md#user-settings) doc. |
| 153 | +
|
| 154 | +## Shutdown |
| 155 | + |
| 156 | +```powershell |
| 157 | +wsl --shutdown |
| 158 | +``` |
| 159 | + |
| 160 | +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](./disk-space.md) or making a change to your [.wslconfig file](./manage.md). |
| 161 | + |
| 162 | +## Terminate |
| 163 | + |
| 164 | +```powershell |
| 165 | +wsl --terminate <Distribution Name> |
| 166 | +``` |
| 167 | + |
| 168 | +To terminate the specified distribution, or stop it from running, replace `<Distribution Name>` with the name of the targeted distribution. |
| 169 | + |
| 170 | +## Identify IP address |
| 171 | + |
| 172 | +- `wsl hostname -I`: Returns the IP address of your Linux distribution installed via WSL 2 (the WSL 2 VM address) |
| 173 | +- `ip route show | grep -i default | awk '{ print $3}'`: Returns the IP address of the Windows machine as seen from WSL 2 (the WSL 2 VM) |
| 174 | + |
| 175 | +For a more detailed explanation, see [Accessing network applications with WSL: Identify IP Address](./networking.md#identify-ip-address). |
| 176 | + |
| 177 | +## Export a distribution |
| 178 | + |
| 179 | +```powershell |
| 180 | +wsl --export <Distribution Name> <FileName> |
| 181 | +``` |
| 182 | + |
| 183 | +Exports a snapshot of the specified distribution as a new distribution file. Defaults to tar format. The filename can be `-` for standard input. Options include: |
| 184 | + |
| 185 | +- `--vhd`: Specifies the export distribution should be a .vhdx file instead of a tar file (this is only supported using WSL 2) |
| 186 | + |
| 187 | +## Import a distribution |
| 188 | + |
| 189 | +```powershell |
| 190 | +wsl --import <Distribution Name> <InstallLocation> <FileName> |
| 191 | +``` |
| 192 | + |
| 193 | +Imports the specified tar file as a new distribution. The filename can be `-` for standard input. Options include: |
| 194 | + |
| 195 | +- `--vhd`: Specifies the import distribution should be a .vhdx file instead of a tar file (this is only supported using WSL 2) |
| 196 | +- `--version <1/2>`: Specifies whether to import the distribution as a WSL 1 or WSL 2 distribution |
| 197 | + |
| 198 | +## Import a distribution in place |
| 199 | + |
| 200 | +```powershell |
| 201 | +wsl --import-in-place <Distribution Name> <FileName> |
| 202 | +``` |
| 203 | + |
| 204 | +Imports the specified .vhdx file as a new distribution. The virtual hard disk must be formatted in the ext4 filesystem type. |
| 205 | + |
| 206 | +## Unregister or uninstall a Linux distribution |
| 207 | + |
| 208 | +To unregister and uninstall a WSL distribution: |
| 209 | + |
| 210 | +```powershell |
| 211 | +wsl --unregister <DistributionName> |
| 212 | +``` |
| 213 | + |
| 214 | +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` would remove Ubuntu from the distributions available in WSL. Running `wsl --list` will reveal that it is no longer listed. |
| 215 | + |
| 216 | +You can also uninstall the Linux distribution app on your Windows machine just like any other store application. To reinstall, find the distribution in the Microsoft Store and select "Launch". |
| 217 | + |
| 218 | +## Mount a disk or device |
| 219 | + |
| 220 | +```powershell |
| 221 | +wsl --mount <DiskPath> |
| 222 | +``` |
| 223 | + |
| 224 | +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](./wsl2-mount-disk.md). Options include: |
| 225 | + |
| 226 | +- `--vhd`: Specifies that `<Disk>` refers to a virtual hard disk. |
| 227 | +- `--name`: Mount the disk using a custom name for the mountpoint |
| 228 | +- `--bare`: Attach the disk to WSL2, but don't mount it. |
| 229 | +- `--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>`. |
| 230 | +- `--partition <Partition Number>`: Index number of the partition to mount, if not specified defaults to the whole disk. |
| 231 | +- `--options <MountOptions>`: There are some filesystem-specific options that can be included when mounting a disk. For example, [ext4 mount options](https://www.kernel.org/doc/Documentation/filesystems/ext4.txt) 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. |
| 232 | + |
| 233 | +> [!NOTE] |
| 234 | +> 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`. |
| 235 | +
|
| 236 | +## Unmount disks |
| 237 | + |
| 238 | +```powershell |
| 239 | +wsl --unmount <DiskPath> |
| 240 | +``` |
| 241 | + |
| 242 | +Unmount a disk given at the disk path, if no disk path is given then this command will unmount and detach ALL mounted disks. |
| 243 | + |
| 244 | +## Deprecated WSL commands |
| 245 | + |
| 246 | +```powershell |
| 247 | +wslconfig.exe [Argument] [Options] |
| 248 | +``` |
| 249 | + |
| 250 | +```powershell |
| 251 | +bash [Options] |
| 252 | +``` |
| 253 | + |
| 254 | +```powershell |
| 255 | +lxrun /[Argument] |
| 256 | +``` |
| 257 | + |
| 258 | +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. |
0 commit comments