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: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
/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
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>
config --default-user has no effect, add this to /etc/wsl.conf instead:[user]
default=your-account
wsl --shutdown and restart for it to take effect.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
7. Notes on sudo
The insults easter egg is not a failureIf entering the wrong sudo password or using an unauthorized account shows something like I'm sorry <user>. I'm afraid I can't do that, that is a humorous rejection message from a sudoers Defaults insults setting (a nod to HAL 9000). It is normal behavior, not a system fault.sudo grep -i insult /etc/sudoers /etc/sudoers.d/* 2>/dev/null
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 insults easter egg is on; the account may lack sudo | Check with groups, and usermod -aG sudo if needed |
/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.
