Skip to content

Installing WSL-ROS2 on Windows

Applicable to: Windows 10 or 11 personal (unmanaged) computers

The WSL-ROS2 Simulation Environment

To support this course we've created a custom ROS 2 environment which runs on Windows 10 or 11 using the Windows Subsystem for Linux (WSL). We call this "WSL-ROS2" and you can download it via the University of Sheffield Software Download Service (University login required).

Note

When you download WSL-ROS2 from the Software Download Service you will receive an email with installation instructions. We recommend that you follow the instructions provided on this page instead, as this page will be kept more up-to-date throughout the semester.

Prerequisites

  1. Your computer must be running Windows 10 Build 19044 or higher, or Windows 11.
  2. Update the GPU drivers for your machine.
  3. Install or update WSL:
    1. If you don't already have WSL installed on your machine then follow these instructions to install it.
    2. If you do already have WSL installed on your machine, then follow these instructions to update it.
  4. Install the Windows Terminal.
  5. Install Visual Studio Code and the WSL VS Code extension.
  6. Install the VcXsrv Windows X Server.

Installing

  1. Go to the IT Services Software Downloads page (you'll need to log in with your university MUSE credentials).

  2. Scroll down to the bottom, where you should see WSL-ROS listed.

    Click on the blue "Request WSL-ROS" button and then wait to receive an email to your university email address.

  3. The email will contain a link to download WSL-ROS2 to your machine as a .zip file (~2 GB).

  4. On your computer, create a new folder in the root of your C:\ drive called WSL-ROS2.

  5. Extract the content of the downloaded .zip file into to the C:\WSL-ROS2\ folder.

  6. Launch PowerShell and enter the follow command to install WSL-ROS2 as a WSL distro on your machine:

    wsl --import WSL-ROS2 $env:localappdata\WSL-ROS2 `
C:\WSL-ROS2\wsl-ros2-v2526.01.tar --version 2

  7. This may take a couple of minutes. Once it's done, you can verify that it was successful with the following command:

    wsl -l -v

    Where WSL-ROS2 should be listed.

  8. Next (optional), open up the Windows Terminal App, then:

    1. Go to Settings (Ctrl+,)
    2. Under Profiles in the left-hand menu, find WSL-ROS2 (or scroll further down and click the Add a new profile button to create it).

    3. Configure the settings for the WSL-ROS2 profile as shown below:

    4. Then, in Startup (back in the left-hand menu again), under Default profile select WSL-ROS2 from the drop-down list.

      This will ensure that each time you open the Windows Terminal App or you press the New Tab () button a WSL-ROS2 Terminal Instance will be launched by default.

Using a Dedicated X Server

WSL-ROS2 requires an XServer in order to render graphical applications (such as Gazebo and RViz)1. You need to make sure you have one up and running whenever you're working with WSL-ROS2.

  1. Having installed VcXsrv in the Prerequisites Section...

  2. Download this config file for VcXsrv and save it to your desktop as wsl_ros_config.xlaunch.

  3. Double click this to launch VcXsrv with the appropriate settings. An icon should then appear in your notification tray (bottom-right) to indicate that the X Server is running:

  4. Launch the WSL-ROS2 environment by launching the Windows Terminal App:

  5. In the WSL-ROS2 terminal instance, try running the empty world Gazebo simulation:

    ros2 launch turtlebot3_gazebo empty_world.launch.py

    This should hopefully present you with something like this:

    Important

    You need to make sure you have the X Server running (by clicking the wsl_ros_config.xlaunch shortcut) every time you work with WSL-ROS2.

See Also

  1. WSL2 does support GUI applications natively, however we are finding that the latest version of Gazebo (Ignition) doesn't seem to play nicely with this, and performance is generally pretty poor. Using a dedicated XServer seems to offer slightly better performance. ↩