04. NVIDIA CUDA Setup with WSL2
WSL2 GPU passthrough requires the NVIDIA Driver for WSL, not the regular Windows display driver. These are separate installations with different version numbers. Download from nvidia.com/Download/index.aspx and select the "Data Center / Driver" category, then filter by "Linux, WSL-internal". The driver version must match or slightly precede the CUDA toolkit version you plan to install inside WSL2.
Install the driver on Windows. You do not need to enable WSL2 GPU scheduling in BIOS—the NVIDIA driver handles this. After installation, verify GPU access from WSL2:
nvidia-smi
# +-----------------------------------------------------------------------------+
# | NVIDIA-SMI 535.183.01 Driver Version: 536.67 CUDA Version: 12.2 |
# |-------------------------------+----------------------+----------------------+
# | GPU Name TCC/WinMode Bus-Id Disp.A | Volatile Uncorr. ECC |
# | 0 NVIDIA GeForce ... Normal 0000:01:00.0 Off | N/A |
# +-----------------------------------------------------------------------------+
If nvidia-smi returns "No devices were found", the WSL2 GPU driver is not loaded. Common causes: (1) you installed the wrong driver version—WSL2 and standard Windows drivers are different packages; (2) Secure Boot is blocking the NVIDIA kernel module; (3) WSL2 was not shut down after driver installation—run wsl --shutdown and retry.
Install CUDA toolkit inside WSL2:
# Add NVIDIA CUDA repository
wget https://developer.download.nvidia.com/compute/cuda/repos/wsl-ubuntu/x86_64/cuda-wsl-ubuntu.pin
sudo mv cuda-wsl-ubuntu.pin /etc/apt/preferences.d/cuda-repository-pin-600
wget https://developer.download.nvidia.com/compute/cuda/12.5.0/local_installers/cuda-repo-wsl-ubuntu-12-5-local_12.5.0-1_amd64.deb
sudo dpkg -i cuda-repo-wsl-ubuntu-12-5-local_12.5.0-1_amd64.deb
sudo cp /var/cuda-repo-wsl-ubuntu-12-5-local/cuda-*-keyring.gpg /usr/share/keyrings/
sudo apt-get update
sudo apt-get -y install cuda-toolkit-12-5
Add CUDA to your PATH:
echo 'export PATH=/usr/local/cuda-12.5/bin:$PATH' >> ~/.bashrc
echo 'export LD_LIBRARY_PATH=/usr/local/cuda-12.5/lib64:$LD_LIBRARY_PATH' >> ~/.bashrc
source ~/.bashrc
Verify with:
nvcc --version
# nvcc: NVIDIA (R) Cuda compiler driver
# Copyright (c) 2005-2024 NVIDIA Corporation
# Built (Tue May 14 15:54:45 2024)
# Cuda compilation tools, release 12.5, V12.5.82
Run nvidia-smi and note the driver version and CUDA version. Run nvcc --version inside WSL2. Verify they are compatible on docs.nvidia.com/cuda/cuda-toolkit-release-notes. If they are not, downgrade or upgrade CUDA toolkit inside WSL2 to match the driver.