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. Save the .zip file to this new folder (C:\WSL-ROS2\)

  6. Launch PowerShell, then run the following commands in order:

    1. Identify the zip file:

      $zipFile = Get-ChildItem "C:\WSL-ROS2\WSL-ROS2_*_SDS.zip" | 
    Sort-Object Name -Descending | 
    Select-Object -First 1

    2. Extract it:

      Expand-Archive -Path $zipFile.FullName `
    -DestinationPath "C:\WSL-ROS2\" -Force

    3. Identify the extracted .tar file:

      $tarFile = Get-ChildItem "C:\WSL-ROS2\wsl-ros2-v*.tar" | 
    Sort-Object Name -Descending | 
    Select-Object -First 1

    4. Import this as a WSL distro:

      wsl --import WSL-ROS2 "$env:localappdata\WSL-ROS2" `
    $tarFile.FullName --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.

Initial Setup

Within a WSL-ROS2 terminal instance, you'll need to run some initial commands to get things set up.

  1. First, run the following command to attempt to use native Graphical User Interface (GUI) support (which should work if you followed all the prerequisites above):

    echo "export XSERVER=false" > $HOME/.diamond/xserver.sh

  2. Then, re-source your .bashrc file for this change to take effect:

    source ~/.bashrc

  3. Run the following ROS command to see if you can launch the Gazebo GUI:

    ros2 launch turtlebot3_gazebo empty_world.launch.py

    This should hopefully present you with something like this:

    If this doesn't work, then you could try using a third-party X Server (VcXsrv) instead...

Using a Third-Party X Server

If you are unable to run GUI apps natively (having completed the steps in the section above), then you could try using a third-party X Server ("VcXsrv") instead. In the prerequisites, you should have already installed VcXsrv.

Note

Only do this if you were unable to launch the robot simulation in the previous section.

  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 a WSL-ROS2 Terminal Instance, run the following:

    echo "export XSERVER=true" > $HOME/.tuos/xserver.sh

  6. Re-source your .bashrc file for this change to take effect:

    source ~/.bashrc

  7. Try running the empty world Gazebo simulation again:

    ros2 launch turtlebot3_gazebo empty_world.launch.py

    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.

Restarting the WSL Engine

If you're having trouble with WSL a restart sometimes helps.

First, close down any WSL-ROS2 terminal windows that you have open (and any connections to WSL-ROS2 in VS Code). Then, launch powershell and shutdown the WSL engine:

wsl --shutdown

Restart the WSL engine by launching a new WSL-ROS2 terminal instance.

See Also