WSL2 CUDA Toolkit 安裝手冊

NVIDIA CUDA WSL2 WSL2 讓 Windows 直接跑 Linux 原生的 CUDA 工具鏈，兼得 Windows 桌面與 Linux 開發環境。關鍵差異在於：驅動只裝在 Windows 端，WSL 內部只裝 toolkit、不裝也不該裝 Linux 原生 driver 套件。這篇涵蓋兩種安裝路徑：有 sudo 權限的系統層級 apt，與完全免 root 的使用者層級 runfile。若你要的是原生 Windows（非 WSL）的 CUDA 與 cuDNN 配置，改看 Windows CUDA & cuDNN 開發環境建置指南。

先確認版本，不要照抄指令裡的版本號本手冊指令以 CUDA Toolkit 13.3、driver 610.43.02、runfile 檔名 cuda_13.3.1_610.43.02_linux.run 為例（2026-07 當時版本）。這些數字會隨 NVIDIA 發布而變動，照抄舊版本號會 404，或裝到與框架不相容的版本。動手前務必：

到 CUDA Downloads 確認當前 toolkit 版本與 runfile 的完整檔名（檔名內含 driver 版本號，最常打錯這裡）。
對照 PyTorch 版本對照表選 CUDA 版本，並非越新越好，先確認你的框架支援。
把後續所有 13.3 / 13-3 / cuda-13.3 換成你實際要裝的版本號。

1. 前置條件確認

Windows 主機端先裝好支援 WSL 的 NVIDIA 驅動（Game Ready 或 Studio 皆可，新版皆內建 WSL CUDA 支援）。驅動只裝在 Windows 端。

更新 WSL 本體與 kernel

在 Windows PowerShell 確認並更新 WSL 版本：

wsl --version
wsl --update

在 WSL 內確認能看到 GPU

此步驟不需要任何 CUDA toolkit，只驗證驅動映射：

nvidia-smi

若這步就抓不到卡，先回頭處理 Windows 端驅動與 WSL kernel 版本，不要往下裝 toolkit。

2. 系統層級安裝（apt，需 sudo）

由具備 sudo 權限的帳號執行一次即可，所有使用者共用同一份 toolkit。

安裝 WSL 專用 keyring 並裝 toolkit

# 清除舊 GPG key（若無舊金鑰會報 key not found，可忽略）
sudo apt-key del 7fa2af80

# 下載 WSL 專用 keyring（注意路徑是 wsl-ubuntu，非一般 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

# 只裝 toolkit，不裝 driver 相關套件
sudo apt-get -y install cuda-toolkit-13-3

安裝路徑：/usr/local/cuda-13.3，預設權限 755，所有使用者皆可讀取執行。

設定全域環境變數（僅 sudo 使用者可執行）

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

所有使用者登入後自動載入此設定，無需個別配置。

多版本共存切換

裝了多個版本時，用 update-alternatives 切換 /usr/local/cuda symlink 指向：

sudo update-alternatives --config cuda

3. 使用者層級安裝（runfile，免 sudo）

無 sudo 權限的帳號用 runfile 裝到自訂目錄，全程不需要 root。

下載並執行 runfile

# 檔名含 driver 版本號，需先至官網確認實際完整檔名（見頁首版本提醒）
# 官方頁面：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：只裝 toolkit 不裝 driver
# --toolkitpath：指定安裝到自己有寫入權限的目錄
# --override：跳過 gcc 版本檢查警告
# --silent：非互動模式
./cuda_13.3.1_610.43.02_linux.run --silent --toolkit --override --toolkitpath=$HOME/cuda-13.3

設定個人環境變數

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. 兩種安裝方式對照

點任一格看補充說明。有 sudo 且多人共用同一穩定版本走 apt；權限受限或多專案各自鎖版本走 runfile。

5. 使用者切換方式

WSL 的身分切換分「單次」「永久預設」「WSL 內臨時」三種。

單次切換（不改預設）
永久改預設登入使用者
WSL 內臨時切換

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

# Windows PowerShell
<distro名稱> config --default-user <username>

若 config --default-user 無反應，改在 /etc/wsl.conf 加：

[user]
default=你的帳號

改完需 wsl --shutdown 後重啟生效。

sudo su - username

6. nvidia-smi 找不到的排查

WSL 環境下 nvidia-smi 由 Windows 驅動掛載至 /usr/lib/wsl/lib/nvidia-smi，與 Linux 原生的 nvidia-utils 套件無關。

切勿依照 apt 建議安裝 nvidia-utils。在 WSL 裝 Linux 原生 driver 工具會覆蓋掉 Windows 掛載的 libcuda.so，反而弄壞 GPU 映射。

確認掛載檔案是否存在

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

若存在，補進 PATH

無 sudo 權限則寫入 ~/.bashrc：

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

若目錄為空，回頭檢查 Windows 端驅動與 WSL kernel 版本。

7. sudo 相關注意事項

insults 彩蛋不是故障若 sudo 密碼輸錯或帳號無權限時，出現類似 I'm sorry <user>. I'm afraid I can't do that 的訊息，這是 sudoers 設了 Defaults insults 的幽默拒絕訊息（致敬 HAL 9000），屬正常行為，非系統故障。

sudo grep -i insult /etc/sudoers /etc/sudoers.d/* 2>/dev/null

檢查帳號是否具備 sudo，以及加入／移除 sudo 群組（後者需 root 執行）：

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

usermod -aG sudo <username>   # 加入
gpasswd -d <username> sudo    # 移除

自動化帳號的權限設計

安裝階段由具 sudo 權限帳號一次性完成。
平日運作帳號不具備 sudo，僅透過 ~/.bashrc 設定個人環境變數。
若必須有限度提權，用 sudoers 的 NOPASSWD 搭配指令白名單，而非開放完整 sudo。

8. 常見錯誤對照表

錯誤訊息	根因	解法
`404 Not Found`（wget runfile）	檔名版本號打錯，runfile 檔名含 driver 版本號	至官方下載頁確認實際完整檔名
`sudo: I'm sorry ... I'm afraid I can't do that`	sudoers 開啟 insults 彩蛋，帳號可能無 sudo 權限	用 `groups` 確認權限，必要時 `usermod -aG sudo`
`/etc/profile.d/cuda.sh: Permission denied`	一般帳號無法寫入系統目錄，sudo 對 `>>` 重導向無效	改寫入 `~/.bashrc`，或用 `sudo tee -a` 寫系統檔
`nvidia-smi: command not found`	PATH 未包含 `/usr/lib/wsl/lib`	補 PATH，勿安裝 nvidia-utils
GPG key 相關錯誤	舊金鑰未清除或未安裝 cuda-keyring	依第 2 節流程重新安裝 keyring

驗證

裝完後跑一遍驗證流程，確認四層都通：驅動映射（nvidia-smi）、編譯器（nvcc）、框架層（PyTorch）、以及 libcuda.so 未被 toolkit 覆蓋。點播放逐行看： nvidia-smi 顯示的 CUDA Version 是驅動支援的最高 CUDA 版本（例如 13.3），不代表你裝的 toolkit 版本；toolkit 版本以 nvcc --version 為準。CUDA 具向下相容性，驅動比 toolkit 新沒問題，反過來不行。

總覽

AI 模型與算法

Docker

軟體開發與工具

知識與管理

網路與自架服務

WSL2 CUDA Toolkit 安裝手冊

1. 前置條件確認

2. 系統層級安裝（apt，需 sudo）

3. 使用者層級安裝（runfile，免 sudo）

4. 兩種安裝方式對照

5. 使用者切換方式

6. nvidia-smi 找不到的排查

7. sudo 相關注意事項

8. 常見錯誤對照表

驗證

​1. 前置條件確認

​2. 系統層級安裝（apt，需 sudo）

​3. 使用者層級安裝（runfile，免 sudo）

​4. 兩種安裝方式對照

​5. 使用者切換方式

​6. nvidia-smi 找不到的排查

​7. sudo 相關注意事項

​8. 常見錯誤對照表

​驗證

1. 前置條件確認

2. 系統層級安裝（apt，需 sudo）

3. 使用者層級安裝（runfile，免 sudo）

4. 兩種安裝方式對照

5. 使用者切換方式

6. nvidia-smi 找不到的排查

7. sudo 相關注意事項

8. 常見錯誤對照表

驗證