Technical Walkthrough

Run RAPIDS on Microsoft Windows 10 Using WSL 2—The Windows Subsystem for Linux

Discuss (3)
As WSL 2 support is EA (experimental), installation instructions have been in flux. This post contains the current instructions and will be updated as appropriate.
  1. Use the MS Blog instructions to install WSL 2
  2. Install the latest production drivers, which are WSL 2 capable
  3. After starting the WSL 2 instance, do not install any additional NVIDIA or CUDA drivers inside of the WSL 2 instance
  4. Inside the WSL 2 instance:
    1. Install the conda or Docker environments.
    2. Install RAPIDS as normal with your environment options of choice

RAPIDS is now more accessible to Windows users! This post walks you through installing RAPIDS on Windows Subsystem for Linux (WSL). WSL is a Windows 10 feature that enables users to run native Linux command-line tools directly on Windows. Using this feature does not require a dual boot environment, taking away complexity and hopefully saving you time. You’ll need access to an NVIDIA GPU with NVIDIA Pascal architecture or newer. Let’s get started right away.

Video 1. RAPIDS on Microsoft Windows Using WSL 2

Getting started

To install RAPIDS, do the following:

  1. Install the latest builds from the Microsoft Insider Program.
  2. Install the NVIDIA preview driver for WSL 2.
  3. Install WSL 2.
  4. Install RAPIDS.

Steps 1–3 can be completed by following the NVIDIA CUDA on WSL guide. However, there are some gotchas. This post walks through each section and points out tips. We recommend opening a tab for the guide alongside this post to make sure that you don’t miss anything.

Before you start, be aware that all the steps in the guide must be carried out in order. It’s particularly important that you install a fresh version of WSL 2 only after installing the new build and driver. Also, CUDA toolkit is installed along with RAPIDS in step 4. Stop following the CUDA on WSL guide after you reach the Setting up CUDA Toolkit section.

Installing the latest builds from the Microsoft Insider program

For your program to run correctly, you must use Windows build version 20145 or higher. When installing the builds, here are some things to note:

  • Start off by navigating to your Windows menu. Select Settings > Update and Security > Windows Update. Make sure that you don’t have any pending Windows updates. If you do, choose Update to make sure that you’re starting out without any.
  • Dev Channel (previously Fast ring): Fast ring is mentioned in the guide as the channel from which to download your build. The name of this channel is now the Dev Channel. Windows calls the process of updating and installing the latest builds flighting. During this process, you must select the DEV Channel when choosing which updates to receive.
  • Downloading and updating requires a restart and can take up to 90 mins. Feel free to grab a coffee while you wait ;).
  • After you’ve restarted your computer, check your build version by running winver through the Windows run command. It can be a little tricky to identify the right number. Figure 1 shows what you should look for after a successful installation (BUILD 20145 or higher).
Image of updated Windows 10 OS Build. The build in the image is OS Build 21296.
Figure 1. The build version is now OS Build 21296, which is sufficient to run WSL 2

When you’ve confirmed your build, move on to step 2.

Installing NVIDIA drivers

Next, install an NVIDIA Driver. Keep the following in mind:

  • Select the driver based on the type of NVIDIA GPU in your system. To verify your GPU type, look for the NVIDIA Control Panel in your Start menu. The name should appear there. For more information, see the CUDA on Windows Subsystem for Linux (WSL) public preview. 
  • When the download is complete, install the driver using the executable. We strongly recommend choosing the default location for saving it.
  • A check to ensure the driver install was successful is to run the command nvidia-smi in PowerShell. It should output a table with information about your GPU and the driver. The driver version is the same as the one that you downloaded.
Image of NVIDIA-SMI table displayed in Windows Powershell. NVIDIA Driver version 465.21 has been correctly installed.
Figure 2. NVIDIA Driver has correctly been installed, version 465.21

Your table might be much shorter and not show any GPU processes. As long as you can see a table and no visible errors, your installation should have been successful. If your driver is successfully installed, jump to step 3. If nothing appears, check whether you’ve missed any of the steps and that your build version is correct.

Installing WSL 2

Next, install WSL 2 with a Linux distribution of your choice. Make sure that the distribution you choose is supported by RAPIDS. The rest of this post describes the installation of WSL 2 with Ubuntu 18.04. These steps should work similarly with other supported distributions.

There are two ways you can install your RAPIDS supporting Linux distribution with WSL 2 on Windows 10. The instructions listed in the Windows guide can seem overwhelming so we’ve distilled it down to the most important parts here:

Using the command line

  • Open your command line and make sure that you’re in the Admin role.
  • Find out which Linux distributions are available and support WSL by typing in the command wsl --list -online.
  • To install the distribution, use the command wsl --install -d <Distribution Name>.
  • For Ubuntu 18.04, this command translated to wsl --install -d Ubuntu-18.04 (be aware of the capital letter U.) This should download and install your Linux distribution.
  • Your selected distribution should either immediately open or appear in your Windows Start menu.
  • If this is not true for you, double-check that your Linux distribution and WSL install was successful by running wsl.exe -list. If no distribution appears, navigate to Programs in Control Panel. Confirm that the Windows Hypervisor Platform and Windows Subsystem for Linux boxes are checked (Figure 3). When confirmed, reboot your computer and try running the install again (possibly twice.) Ideally, the WSL terminal should pop up right after the installation.
Image of Windows Features list. Windows Hypervisor Platform and Windows Subsystem for Linux boxes are checked successfully.
Figure 3. In case your WSL terminal install doesn’t work right away, make sure the folders checked preceding are checked on your system as well.
  • When opening your WSL terminal for the first time, you are prompted to set up a default (non-root) user. Make sure that you do not skip this step, as you must be the root user to install other packages.
  • When you’ve set the default user, reboot your machine. When you return, you’ll be all set for step 4.

Through the Microsoft Store

  • If you already know which distribution to use, download and install it directly from the Microsoft Store on your machine.
  • Set the default user and do a reboot in this case as well.

When you’ve completed this step, you’re ready to install the CUDA Toolkit and are almost done!

Install RAPIDS

  • If you don’t have it already, start by installing and activating Miniconda in your WSL terminal. You use the conda command to install the packages needed in this step.
  • You can install RAPIDS with a single conda command. Just type the following line in and you’re all set.
# for CUDA 11.0
conda install -c rapidsai -c nvidia -c numba -c conda-forge \
cudf=21.06 python=3.7 cudatoolkit=11.0
# or, for CUDA 11.2
conda install -c rapidsai -c nvidia -c numba -c conda-forge \
cudf=21.06 python=3.7 cudatoolkit=11.2
view raw rapids_wsl hosted with ❤ by GitHub
Type this command into your terminal to install RAPIDS.

To test your installation, start up the RAPIDS virtual environment:

  • Typing out conda info --envs, which lets you know the name of the installed RAPIDS environment.
    • cuDF is supported only on Linux and with Python versions 3.7 and later.
  • Import any RAPIDS library or start a Jupyter notebook.

Hopefully, your installation was successful. RAPIDS is open-source, so if you managed to get this far and would like to contribute, take another look at the contributing guide of any of our libraries or join the RAPIDS Slack channel to find out more.

This post was originally published on the RAPIDS AI blog.