# Configure and run WSL with various Linux distributions

## In this learning path

- [Introduction](https://learn.arm.com/learning-paths/laptops-and-desktops/wsl2/)
- [Configure and run WSL with various Linux distributions](https://learn.arm.com/learning-paths/laptops-and-desktops/wsl2/setup/)
- [Run graphical Linux applications](https://learn.arm.com/learning-paths/laptops-and-desktops/wsl2/wslg/)
- [Enable systemd in WSL](https://learn.arm.com/learning-paths/laptops-and-desktops/wsl2/systemd/)
- [Use SSH to connect to WSL](https://learn.arm.com/learning-paths/laptops-and-desktops/wsl2/ssh/)
- [Connect to WSL using RDP and VNC](https://learn.arm.com/learning-paths/laptops-and-desktops/wsl2/rdp/)
- [Developing with VS Code on WSL](https://learn.arm.com/learning-paths/laptops-and-desktops/wsl2/vscode/)
- [Import file systems into WSL](https://learn.arm.com/learning-paths/laptops-and-desktops/wsl2/import/)
- [Backup a WSL filesystem](https://learn.arm.com/learning-paths/laptops-and-desktops/wsl2/backup/)
- [Next Steps](https://learn.arm.com/learning-paths/laptops-and-desktops/wsl2/_next-steps/)

## Before you begin
This Learning Path assumes you have a Windows on Arm computer such as the Lenovo Thinkpad X13s laptop running Windows 11.

WSL is useful if you are developing on Arm virtual machine instances in the cloud. It is also useful if you are developing with embedded Linux on Arm on single board computers.

Using the same Arm architecture on your local development machine and on the cloud or your embedded board provides interoperability, consistency, and saves time.

## Introduction to WSL 2
Software developers often use Linux for creating applications and containers. Windows on Arm includes the [Windows Subsystem for Linux 2](https://docs.microsoft.com/en-us/windows/wsl/about) (WSL 2).

WSL 2 replaces the system call translation layer provided in WSL 1 with the latest virtualization technology to run a complete Linux kernel. WSL 2 running on a Windows on Arm computer provides a complete Linux kernel and supports many Arm Linux distributions.

WSL 2 can run containers for application development. WSL 2 provides much faster file I/O compared to WSL 1.

## Install WSL 2
Installing WSL 2 requires Windows 11. It is also possible to install WSL 2 on certain Windows 10 versions, but these instructions were tested on Windows 11. Windows 11 is recommended to complete all of the examples in this Learning Path. All of the examples have been tested using WSL 2. If only WSL is specified it means WSL 2.

Here is the short version on how to install WSL 2. Microsoft documentation provides a [quickstart](https://docs.microsoft.com/en-us/windows/wsl/install-win10) with full details on how to install WSL 2. There are also numerous tutorials available (for non-Arm architectures).

There are three steps to setup WSL 2.

1. Enable Windows features
   Open “Turn Windows features on or off” in the Windows control panel and make sure “Virtual Machine Platform” and “Windows Subsystem for Linux” are checked.

   ![Image Alt Text:Turn Windows features on or off](https://dev-to-uploads.s3.amazonaws.com/i/9kubnntqzsfq9lxfrfrk.PNG#center)

2. Download WSL  
   Download and install WSL 2 from the [Microsoft Store](https://apps.microsoft.com/store/detail/windows-subsystem-for-linux-preview/9P9TQF7MRM4R).

3. Set the default version to WSL 2  
   Open a Windows PowerShell or Command Prompt and run the command:

   ```bash
   wsl --set-default-version 2
   ```

   The output from this command will look like:

   ```
   __output__
   For information on key differences with WSL 2 please visit https://aka.ms/wsl2
   __output__
   The operation completed successfully.
   ```

## Install a Linux distribution
Once WSL 2 is installed, the Microsoft store is the easiest place to find a Linux distribution. [Installing Ubuntu 24.04](https://apps.microsoft.com/detail/9nz3klhxdjp5?hl=en-US&gl=US) is quick and easy from the store.

There are other Linux distributions available in the Microsoft Store. Make sure to select the ones that work on Arm. Some do not work and it may be some trial-and-error to identify those that work on Arm.

Another way to install Linux distributions is using the WSL command.

Open a Windows PowerShell or Command Prompt and list the distributions available:

```bash
wsl --list --online
```

The output will list the available distributions:

```
__output__
The following is a list of valid distributions that can be installed.
__output__
Install using 'wsl.exe --install <Distro>'.
__output__

NAME                   FRIENDLY NAME
AlmaLinux-8            AlmaLinux OS 8
AlmaLinux-9            AlmaLinux OS 9
AlmaLinux-Kitten-10    AlmaLinux OS Kitten 10
AlmaLinux-10           AlmaLinux OS 10
Debian                 Debian GNU/Linux
FedoraLinux-42         Fedora Linux 42
Ubuntu                 Ubuntu
Ubuntu-24.04           Ubuntu 24.04 LTS
kali-linux             Kali Linux Rolling
openSUSE-Tumbleweed    openSUSE Tumbleweed
openSUSE-Leap-16.0     openSUSE Leap 16.0
Ubuntu-20.04           Ubuntu 20.04 LTS
Ubuntu-22.04           Ubuntu 22.04 LTS
openSUSE-Leap-15.6     openSUSE Leap 15.6
```

Install a distribution from this list:

```bash
wsl --install Ubuntu-24.04
```

Be patient, the download and install takes some time.

After installation, each Linux distribution will have an icon on the Windows application menu. Use this icon to start WSL with the Linux distribution.

A new window should open with a Linux shell.

![Image Alt Text:Running Linux](/learning-paths/laptops-and-desktops/wsl2/wsl-linux.png)

## Use Windows terminal
Windows Terminal is a great way to use WSL. It can be installed from the [Microsoft Store](https://apps.microsoft.com/store/detail/windows-terminal/9N0DX20HK701). The [repository is on GitHub](https://github.com/microsoft/terminal).

Windows Terminal supports multiple command lines: PowerShell, Command Prompt, and WSL Linux. It is very configurable.

## Run bash.exe
From Windows, Bash can be used to run commands in WSL.

You can enter the default WSL distribution by running bash from a Windows Command Prompt:

```bash
bash.exe
```

You can exit Bash and return back to the Windows Command Prompt with:

```bash
exit
```

Use the `-c` option to `bash.exe` to run a command in WSL and collect the result.

For example, to list the contents of /usr/bin in WSL from a Windows Command Prompt run:

```bash
bash.exe -c "ls /usr/bin"
```

## WSL command line options
Here is a quick review the WSL command line options.

Print the usage information and see the command line arguments:

```bash
wsl --help
```

List the installed distributions:

```bash
wsl --list
```

List only the running distributions:

```bash
wsl --list --running
```

Terminate a running distribution:

```bash
wsl --terminate Ubuntu-24.04
```

Shutdown all running distributions:

```bash
wsl --shutdown
```

Unregister the Linux distribution and delete the filesystem:

```bash
wsl --unregister Ubuntu-24.04
```

Update WSL to the latest version:

```bash
wsl --update
```

Start the default distribution:

```bash
wsl
```