To install the CUDA Toolkit on WSL 2, install a current NVIDIA driver on Windows (not inside Linux), then install the WSL-specific CUDA Toolkit package inside your Linux distribution, and verify with nvidia-smi and nvcc. The toolkit supplies the compiler and libraries, while the Windows driver supplies GPU access.
The most common failure is installing a Linux NVIDIA driver inside WSL, which breaks the setup. This guide covers the correct order, the exact choices to make on NVIDIA’s download page, how to confirm everything works, and the mistakes that cause most errors.
How CUDA on WSL 2 Is Structured
WSL 2 runs a real Linux kernel in a lightweight virtual machine, and NVIDIA’s Windows driver exposes the GPU into that environment. A small stub library appears inside the Linux system, which forwards GPU calls to the Windows driver. Because of this design, the Linux side must never install its own display driver.
| Component | Where it lives | What it does |
|---|---|---|
| NVIDIA GPU driver | Windows host | Provides GPU access, including to WSL |
| WSL 2 and its kernel | Windows | Runs the Linux environment |
| CUDA Toolkit | Inside the Linux distribution | Compiler (nvcc), libraries, headers |
| Linux NVIDIA driver | Do not install | Would conflict with the Windows driver |
Requirements change over time, so check the current NVIDIA and Microsoft documentation for supported Windows builds and driver versions. In general you need a CUDA-capable NVIDIA GPU, a recent Windows 11 or Windows 10 build that supports GPU in WSL, and a WSL 2 distribution such as Ubuntu.
Step-by-Step Installation
Step 1: Update the Windows driver
Install the latest NVIDIA driver for your GPU from NVIDIA’s official driver page or the NVIDIA app. Current Windows drivers already include WSL support, so there is no separate download. Restart if the installer asks.
Step 2: Update WSL and confirm version 2
Open a Windows terminal and run wsl –update, then wsl –shutdown to restart the subsystem. Run wsl -l -v to list distributions and confirm the VERSION column shows 2. If it shows 1, convert it with wsl –set-version followed by the distribution name and the number 2.
Step 3: Confirm the GPU is visible
Open your Linux distribution and run nvidia-smi. A table listing your GPU and the driver version means the Windows driver is passing through correctly. If the command is missing or reports an error, fix this before installing anything else.
Step 4: Install the toolkit
On NVIDIA’s CUDA Toolkit download page, choose Linux, then x86_64, then WSL-Ubuntu, then version 2.0, then your preferred installer type. The page displays a short list of commands to copy. They add NVIDIA’s repository key and package source, update the package list, and install the toolkit. Use the toolkit package name, which looks like cuda-toolkit followed by the version numbers, and not the generic cuda or cuda-drivers packages, since those can pull in a Linux driver.
Verify the Installation
The toolkit installs under a versioned folder in /usr/local, with a symbolic link named cuda. The compiler may not be found until you add its folder to your shell paths. Add /usr/local/cuda/bin to the front of the PATH variable and /usr/local/cuda/lib64 to the LD_LIBRARY_PATH variable in your shell profile file, then reopen the terminal.
- Run nvcc –version. It should print the compiler release, confirming the toolkit is installed.
- Run nvidia-smi again. It reports the driver version and the highest CUDA version that driver supports.
- Compare the two. The toolkit version should not be newer than the CUDA version nvidia-smi reports. If it is, update the Windows driver.
- Optionally compile a small sample program, such as the device query sample from NVIDIA’s CUDA samples, to confirm the toolchain builds and runs.
Note that nvidia-smi and nvcc report different things. nvidia-smi shows what the driver supports; nvcc shows what the installed toolkit is. Seeing two different version numbers is normal.
Common Mistakes and Fixes
- Installing a Linux driver in WSL. Symptom: nvidia-smi stops working or reports a mismatch. Fix: remove the NVIDIA driver packages inside Linux and rely on the Windows driver only. Back up your work first.
- Using the wrong repository. The standard Ubuntu desktop CUDA packages can include driver components. Always choose the WSL-Ubuntu option.
- Running WSL 1. GPU access needs WSL 2. Convert the distribution if needed.
- Outdated Windows driver. A new toolkit with an old driver fails at runtime. Update the driver.
- nvcc not found. The toolkit is installed but the folder is not in PATH. Add it as described above.
- Not enough disk space. The toolkit takes several gigabytes. Check free space in the distribution before installing.
- Mixing repository sources. Old keys or sources from earlier attempts can cause update errors. Clean up outdated entries following NVIDIA’s current instructions.
Do You Even Need the Full Toolkit?
Many people install the toolkit when they do not need it. Popular machine learning frameworks such as PyTorch and TensorFlow typically ship their own CUDA runtime libraries inside their packages, so they only need the Windows driver and a compatible package version. The full toolkit is needed when you compile your own CUDA code with nvcc, build projects from source that call for it, or use specific developer tools.
If you only want to run existing Python machine learning code, try installing the framework first and check that it detects the GPU. Add the full toolkit only if a build or a dependency asks for it. Check each project’s current documentation, since packaging practices change.
Choosing the Right Toolkit Version
The toolkit version you pick should match what your software needs and what your Windows driver supports. Start with the project you want to build or run, and read its documentation for the CUDA version it expects. Then run nvidia-smi and note the CUDA version in the top corner of its table, which is the highest version the driver can support. Pick a toolkit version at or below that number.
Multiple toolkit versions can sit side by side under the same parent folder, each in its own versioned directory, and the cuda symbolic link points to the one that is active. To switch, change which version the link or your shell paths point to. This is handy when different projects need different releases, but keep track of which one is active so build tools find the right compiler.
Using the Toolkit After Installation
With the toolkit in place, a typical first project is a small program compiled with nvcc that launches a trivial kernel and copies a result back to the host. If it compiles and prints the expected output, the compiler, libraries, and GPU access all work together. If compilation works but the program fails at runtime with a message about no CUDA-capable device, the driver pass-through is the likely cause, so go back to the Windows driver and the WSL version checks.
For containers, NVIDIA offers a container toolkit that lets Docker use the GPU inside WSL. That is a separate component with its own current installation steps, and it is only needed if you plan to run GPU containers. Developer tools such as profilers and debuggers have their own WSL requirements as well, so check NVIDIA’s current documentation for support status before depending on them.
Finally, keep the setup tidy. Update WSL and the Windows driver occasionally, avoid mixing installation methods for the same toolkit version, and keep notes on which commands you ran. If an installation goes wrong, it is often faster to remove the toolkit packages and repository entries, then repeat the official steps cleanly, than to patch a broken state.
Related guides
- What Does Manage Gpu Performance Counters Mean On Nvidia Hardware
- Low Profile Nvidia Graphics Cards For Small Form Factor Pcs
- Nvidia App Error Your System Configuration Is Not Supported
Frequently Asked Questions
Do I install the NVIDIA driver inside WSL?
No. Install the driver only on Windows. The WSL Linux environment uses the Windows driver through a pass-through layer, and installing a Linux driver there causes conflicts.
Why does nvidia-smi show a different CUDA version than nvcc?
nvidia-smi reports the highest CUDA version the driver supports, while nvcc reports the installed toolkit version. They do not need to match, as long as the toolkit is not newer than what the driver supports.
Which CUDA package should I install on WSL?
Use the toolkit package from NVIDIA’s WSL-Ubuntu repository, named cuda-toolkit with a version suffix. Avoid the generic cuda and cuda-drivers packages, which can try to install a driver.
Can I use CUDA in WSL 1?
No. GPU compute is available only in WSL 2. Check the version with wsl -l -v and convert the distribution if necessary.
Write Your Review
No reviews yet. Be the first to share your experience!