ContextQMD
Back to Riot

Installing WSL (Windows-only)

doc/guides/getting-started/install-wsl.mdx

2026.07-devel9.2 KB
Original Source

:::note The following guide is for Windows users only.

It explains the process of installing Ubuntu LTS via Windows Subsystem for Linux (WSL) on a Windows machine.

If you are using a different operating system, please refer to the general guide on how to use RIOT. :::

Install Ubuntu LTS

  1. Open the Windows Store
  2. Type "Ubuntu LTS" in the search bar
  3. Click on the most recent version (highest number) of Ubuntu LTS found. As of February 2024, this is version Ubuntu 22.04.3 LTS.

  1. Click on the button labeled "Get"

It will take a while for Ubuntu LTS to be installed.

Eventually, the installation completes.

  1. Click on the button labeled "Open"

:::caution If the Windows Subsystem for Linux (WSL) has not yet been enabled, an error such as below will show. Not to worry, the next section got you covered. :::

Enabling WSL

:::note If an Ubuntu terminal opened just fine, proceed directly to the next section. This section will show how to enable WSL for those who hit the error. :::

  1. Search for "powershell" in the search field of the task bar
  2. Right-click on the hit "Windows PowerShell"
  3. Click "Run as administrator"

  1. Click "Yes" to confirm running the PowerShell as administrator

  • Type wsl --install and confirm with the return-key.
  • After a while, the following message should appear:

  • Now reboot Windows to complete the installation

The reboot will take longer than usual due to the installation of WSL. You may see a screen like above for some time. Once the reboot is completed, an Ubuntu terminal should open automatically.

Setup Ubuntu LTS

You should now see an Ubuntu terminal such as:

<details> <summary> If no Ubuntu terminal has opened, click here to see how to open it </summary>

  1. Click on the Start / Windows button in the task bar
  2. Click on the "Ubuntu" entry
</details>
  • Enter a user name of your choice, memorize it, and confirm with the return-key
  • Enter a password of your choice, memorize it, and confirm with the return-key
  • Repeat the password and confirm with the return-key

:::caution When typing passwords in the Ubuntu terminal, the chars entered will not appear on the screen and neither will appear *. You will have to type "blindly". This is an intentional security feature. :::

:::note If you fail to repeat the password correctly, the setup will just again. So no need to worry. :::

  • Once you successfully have entered user name and password, you should see something like this:

  • now type (without quotation signs) "sudo apt update" and confirm with the return-key
  • you will be asked for you password. Enter it and confirm with the return key

:::caution When typing the password, you will no get any visible feedback such as the typed password or * chars. This is an intentional security feature. :::

  • Once you successfully entered the password, something like this will show up:

:::note The command sudo apt update only updates the list of available software packages in Ubuntu. Updating the installed software requires to additionally run sudo apt upgrade :::

  • Now type sudo apt upgrade and confirm with the return-key

:::note This time you likely will not need to confirm with your password again. The sudo command that allows you to run administrative commands such as apt update will skip the password entry, when heuristics indicate that you have not left your machine since you last confirmed a command with your password. :::

  • This command will list which packages are about to be updated. Confirm with with the return-key
  • Eventually after all software packages in Ubuntu have been updated, you will see something like this:

:::note It is recommended to regularly update the installed software in Ubuntu using sudo apt update followed by sudo apt upgrade :::

Installing VS Code

  1. Click on the Windows Store icon to open the Windows store
  2. Type vs code in the search bar
  3. Click on the "Visual Studio Code by Microsoft Corporation" search result (not shown in the screenshot above)
  4. In the Windows Store page of VS Code (as shown in the screenshot above), click on the button labeled "Install"

  • Downloading and installing VS Code by the Store App may take some time
  • Eventually, it should show something like this:

  • Now, launch VS Code via the start menu
  • On the first launch, VS code will look similar to this:

  • You can select a theme of you liking
  • You might want to dial back the data collection by Microsoft by clicking on "opt out"

  1. Open the extension marketplace by clicking on the extensions icon in the left menu bar
  2. Search for wsl in the search field
  3. Click on the "Install" button for the "WSL" extension by "Microsoft"

:::note The installation of the WSL extension will complete the next time you open Ubuntu terminal. If the Ubuntu terminal was still open, close it using the exit comment and launch it again. :::

Installing usbipd-win

  1. Open the release page of usbipd-win
  2. Download the installer (file extension .msi) of the most recent release

Once the download is completed:

  1. Open the downloaded installer

  1. Confirm that you indeed want to execute the installer by clicking "OK".

The setup of usbipd-win opens.

  1. Click on the "Install" button to proceed with the installation.

  1. Confirm the installation by clicking on "Yes".

Eventually, the setup will inform you of the completion of the installation.

  1. Click the "Close" button to acknowledge.

Attach a USB Device to WSL

:::note Attaching a USB device to WSL needs to be repeated after any of the following happens:

  1. Windows has been restarted (or hibernated)
  2. WSL (the Ubuntu terminal window) has been restarted
  3. The USB device has been lost (e.g. unplugging and plugging back in) :::

:::note You do not need to install the Windows USB drivers, Linux will use its own anyway. All supported board run on Linux out of the box without the need of drivers to be installed. :::

  1. Search for powershell in search field in the task bar
  2. Right-click on the search result "Windows PowerShell"
  3. Select "Run as administrator"

  1. Click on "Yes" to confirm running the PowerShell as admin

  1. Type the command usbipd list and confirm with the return-key
  2. Identify the USB device to share. In this guide we use an ESP32 development board, which almost all use an USB to UART bridge (here the CP2104).
  3. Run usbipd bin --busid <BUSID>, but replace <BUSID> with the correct BUSID. E.g. 2-5 for the CP2104 identified in step 2.
  4. Run usbipd attach --wsl --busid <BUSID>
    • If an error (such as above in red) is shown that WSL is not running, just start the Ubuntu terminal now and repeat (step 5.). If it worked the first time, no need to run it again.

:::note If you have trouble identifying the USB device to attach, unplug before running usbipd list. Run it again with the USB device plugged in. The new entry in the list is the device you want to attach to WSL. :::

Now that you have successfully installed Ubuntu LTS and enabled WSL on your Windows we can proceed with the next steps to setup our development environment.