WSL2 CUDA Toolkit Installation Guide

NVIDIA CUDA WSL2 WSL2 lets Windows run the native Linux CUDA toolchain, giving you both the Windows desktop and a Linux development environment. The key distinction: the driver is installed only on the Windows side; inside WSL you install only the toolkit and must not install the native Linux driver packages. This guide covers both installation paths: system-wide apt (requires sudo) and the fully root-free user-level runfile. If you want native Windows (not WSL) CUDA and cuDNN configuration instead, see the Windows CUDA & cuDNN Development Environment Setup Guide.

Confirm your versions first; do not copy the version numbers in these commands verbatimThis guide uses CUDA Toolkit 13.3, driver 610.43.02, and the runfile named cuda_13.3.1_610.43.02_linux.run as an example (the versions current as of 2026-07). These numbers change with each NVIDIA release; copying an old version number will 404 or install a version incompatible with your framework. Before you start:

Check the current toolkit version and the runfile’s exact filename on CUDA Downloads (the filename embeds the driver version number, which is the most common place to get it wrong).
Pick your CUDA version against the PyTorch version compatibility table. Newer is not always better; confirm your framework supports it first.
Replace every 13.3 / 13-3 / cuda-13.3 below with the version you are actually installing.

1. Prerequisites

On the Windows host, install a WSL-capable NVIDIA driver (Game Ready or Studio both work; recent versions include WSL CUDA support). The driver is installed only on the Windows side.

Update WSL and the kernel

In Windows PowerShell, confirm and update WSL:

wsl --version
wsl --update

Confirm the GPU is visible inside WSL

This step needs no CUDA toolkit; it only verifies the driver mapping:

nvidia-smi

If the GPU is not detected here, go back and fix the Windows-side driver and WSL kernel version first. Do not proceed to install the toolkit.

2. System-wide install (apt, requires sudo)

An account with sudo runs this once, and all users share the same toolkit.

Install the WSL keyring and the toolkit

# Remove the old GPG key (if none exists it reports "key not found", which is fine)
sudo apt-key del 7fa2af80

# Download the WSL-specific keyring (note the path is wsl-ubuntu, not the regular ubuntu repo)
wget https://developer.download.nvidia.com/compute/cuda/repos/wsl-ubuntu/x86_64/cuda-keyring_1.1-1_all.deb
sudo dpkg -i cuda-keyring_1.1-1_all.deb
sudo apt-get update

# Install only the toolkit, not any driver packages
sudo apt-get -y install cuda-toolkit-13-3

Install path: /usr/local/cuda-13.3, default permissions 755, readable and executable by all users.

Set global environment variables (sudo users only)

sudo tee /etc/profile.d/cuda.sh > /dev/null << 'EOF'
export PATH=/usr/lib/wsl/lib:/usr/local/cuda-13.3/bin${PATH:+:${PATH}}
export LD_LIBRARY_PATH=/usr/local/cuda-13.3/lib64${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}
EOF
sudo chmod +x /etc/profile.d/cuda.sh

All users load this automatically at login; no per-user configuration needed.

Switch between coexisting versions

With multiple versions installed, use update-alternatives to switch the /usr/local/cuda symlink:

sudo update-alternatives --config cuda

3. User-level install (runfile, no sudo)

An account without sudo installs via runfile into a custom directory, with no root required at any point.

Download and run the runfile

# The filename embeds the driver version number; confirm the exact filename on the official site first (see the version warning at the top)
# Official page: https://developer.nvidia.com/cuda-downloads
wget https://developer.download.nvidia.com/compute/cuda/13.3.1/local_installers/cuda_13.3.1_610.43.02_linux.run

chmod +x cuda_13.3.1_610.43.02_linux.run

# --toolkit: install only the toolkit, not the driver
# --toolkitpath: install into a directory you have write access to
# --override: skip the gcc version check warning
# --silent: non-interactive mode
./cuda_13.3.1_610.43.02_linux.run --silent --toolkit --override --toolkitpath=$HOME/cuda-13.3

Set personal environment variables

cat >> ~/.bashrc << 'EOF'
export PATH=/usr/lib/wsl/lib:$HOME/cuda-13.3/bin${PATH:+:${PATH}}
export LD_LIBRARY_PATH=$HOME/cuda-13.3/lib64${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}
EOF
source ~/.bashrc

4. Comparing the two installation methods

Click any cell for details. Use apt when you have sudo and multiple users share one stable version; use runfile when permissions are restricted or each project pins its own version.

5. Switching users

WSL identity switching comes in three forms: one-time, permanent default, and temporary inside WSL.

One-time (does not change default)
Change the permanent default login user
Temporary switch inside WSL

# Windows PowerShell
wsl --user root
wsl --user <username>

# Windows PowerShell
<distro-name> config --default-user <username>

If config --default-user has no effect, add this to /etc/wsl.conf instead:

[user]
default=your-account

Run wsl --shutdown and restart for it to take effect.

sudo su - username

6. Troubleshooting a missing nvidia-smi

Under WSL, nvidia-smi is mounted from the Windows driver at /usr/lib/wsl/lib/nvidia-smi; it has nothing to do with the native Linux nvidia-utils package.

Do not follow apt’s suggestion to install nvidia-utils. Installing native Linux driver tools inside WSL overwrites the Windows-mounted libcuda.so and breaks the GPU mapping.

Check whether the mounted file exists

ls -la /usr/lib/wsl/lib/ | grep -i nvidia

If it exists, add it to PATH

Without sudo, write it into ~/.bashrc:

echo 'export PATH=/usr/lib/wsl/lib${PATH:+:${PATH}}' >> ~/.bashrc
source ~/.bashrc
nvidia-smi

If the directory is empty, go back and check the Windows-side driver and WSL kernel version.

7. Notes on sudo

I'm afraid I can't do that is not the insults easter egg, and not a failureThis HAL 9000 line is the fixed denial message of sudo-rs (the Rust rewrite of sudo; the default since Ubuntu 25.10 and kept in 26.04 LTS, while 24.04 still defaults to the original sudo). It appears whenever sudoers does not allow you to run the command: the account is not in the sudo group, or it has sudo but not for this command or target user. It means the permission was denied, which is normal behavior, not a system fault. A wrong password takes a separate authentication-failure path and does not print this line.Defaults insults is the real easter egg, but it exists only in the original sudo: on a wrong password it answers with a random humorous line, and it is off by default. sudo-rs ignores the setting (marked ignored in its source). For an account with no permission, the original sudo prints <user> is not in the sudoers file instead.

sudo --version | head -n 1                                       # sudo-rs is shown for the Rust version
sudo grep -rn insults /etc/sudoers /etc/sudoers.d/ 2>/dev/null   # original sudo: check whether insults is on

Check an account’s actual sudo grants, and add or remove it from the sudo group (the latter requires root). Judge permission by the grants that sudo -l -U <username> lists; groups alone is not enough, because a grant can also come from a separate file in /etc/sudoers.d/:

groups <username>
sudo -l -U <username>

usermod -aG sudo <username>   # add
gpasswd -d <username> sudo    # remove

Permission design for automation accounts

Do the install once from an account with sudo.
Keep the day-to-day account without sudo, setting personal env vars via ~/.bashrc only.
If limited elevation is unavoidable, use a sudoers NOPASSWD entry with a command allowlist rather than granting full sudo.

8. Common errors

Error message	Root cause	Fix
`404 Not Found` (wget runfile)	Wrong version number; the runfile filename embeds the driver version	Confirm the exact filename on the official download page
`sudo: I'm sorry ... I'm afraid I can't do that`	The sudo-rs permission-denied message: sudoers does not grant this account the command (unrelated to insults)	Check the actual grants with `sudo -l -U <username>`; if needed, `usermod -aG sudo` or add a grant under `/etc/sudoers.d/`
`/etc/profile.d/cuda.sh: Permission denied`	A normal account cannot write to system directories; sudo does not apply to the `>>` redirect	Write to `~/.bashrc` instead, or use `sudo tee -a` for the system file
`nvidia-smi: command not found`	PATH does not include `/usr/lib/wsl/lib`	Add it to PATH; do not install nvidia-utils
GPG key errors	Old key not removed or cuda-keyring not installed	Reinstall the keyring per Section 2

Verification

After installing, run the full verification flow to confirm all four layers work: the driver mapping (nvidia-smi), the compiler (nvcc), the framework layer (PyTorch), and that libcuda.so was not overwritten by the toolkit. Press play to watch it run line by line: The CUDA Version shown by nvidia-smi is the maximum CUDA version the driver supports (e.g. 13.3), not the toolkit version you installed; the toolkit version comes from nvcc --version. CUDA has backward compatibility: a driver newer than the toolkit is fine, the reverse is not.

Overview

AI Models & Algorithms

Docker

Software & Tools

Knowledge & Method

Networking & Self-hosting

WSL2 CUDA Toolkit Installation Guide

1. Prerequisites

2. System-wide install (apt, requires sudo)

3. User-level install (runfile, no sudo)

4. Comparing the two installation methods

5. Switching users

6. Troubleshooting a missing nvidia-smi

7. Notes on sudo

8. Common errors

Verification

​1. Prerequisites

​2. System-wide install (apt, requires sudo)

​3. User-level install (runfile, no sudo)

​4. Comparing the two installation methods

​5. Switching users

​6. Troubleshooting a missing nvidia-smi

​7. Notes on sudo

​8. Common errors

​Verification

1. Prerequisites

2. System-wide install (apt, requires sudo)

3. User-level install (runfile, no sudo)

4. Comparing the two installation methods

5. Switching users

6. Troubleshooting a missing nvidia-smi

7. Notes on sudo

8. Common errors

Verification