首页/文章/系统折腾

WSL2 Ubuntu 安装 CUDA Toolkit

太阳作者太阳
原创内容采用 CC-4.0 协议发布，转载请注明出处
CUDAUbuntu环境

原笔记只有一段 WSL 安装命令，没有留下测试输出。这里聚焦 WSL2 的 Ubuntu 工作流；NVIDIA 官方说明，WSL 使用 Windows 主机驱动映射出的 CUDA 接口，WSL 内不应安装 Linux NVIDIA 显示驱动。CUDA on WSL User Guide是选择这条边界的依据。

先确认运行环境

在 Windows PowerShell 中更新 WSL，并确认发行版运行在 WSL2：

wsl.exe --update
wsl.exe --status
wsl.exe -l -v

在 Windows 主机安装与 GPU 匹配的 NVIDIA 驱动，然后进入 Ubuntu：

wsl.exe

WSL2 的 GPU 支持依赖 Windows 驱动、Windows 版本和 WSL 内核。驱动版本、GPU 型号和 CUDA Toolkit 版本要一起查 NVIDIA 的支持矩阵；不要把“能运行 nvidia-smi”理解成已经安装了编译工具包。

选择 Toolkit 版本

先在 NVIDIA CUDA Downloads 选择 Linux、x86_64、Ubuntu、WSL-Ubuntu 和目标版本，按照页面生成的仓库命令安装。需要稳定复现时，选择带版本号的 cuda-toolkit-X-Y 包；不希望安装或升级 Linux 驱动时，不要在 WSL2 选择 cuda、cuda-X-Y 或 cuda-drivers 这类可能带驱动的 meta-package。NVIDIA 的 CUDA on WSL 安装说明明确建议使用不覆盖 WSL 映射驱动的 WSL-Ubuntu Toolkit 包。

在 Ubuntu / WSL2 安装

下面保留原笔记的 cuda-keyring 做法，但版本和下载地址必须以 CUDA Downloads 页面针对当前 Ubuntu 代号生成的内容为准：

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
sudo apt-get install -y cuda-toolkit

cuda-toolkit 只安装开发工具包，适合 WSL2。原笔记中的 nvidia-cuda-toolkit 是 Ubuntu 发行版包的另一条路线；不要把它和 NVIDIA CUDA 仓库混用后再排查版本。若仓库页面给出了带版本号的包，应优先按页面选择，例如 cuda-toolkit-12-4，以免无意间跟随大版本更新。

环境变量与验证

先找出实际安装目录：

command -v nvcc
nvcc --version
nvidia-smi

若 nvcc 已安装但不在 PATH，可在当前 shell 临时设置：

export PATH=/usr/local/cuda/bin:"$PATH"
nvcc --version

nvidia-smi 验证 Windows 驱动通过 WSL 暴露的 GPU 访问，nvcc --version 验证 Toolkit 编译器；二者版本显示不同并不自动表示错误。若运行时提示动态库缺失，按 CUDA Linux 安装指南检查实际安装路径和对应的运行时配置，不要为了补路径盲目追加 LD_LIBRARY_PATH。

下载 CUDA Samples 后编译 deviceQuery：

git clone https://github.com/NVIDIA/cuda-samples.git
cd cuda-samples/Samples/1_Utilities/deviceQuery
make
./deviceQuery

输出应包含 CUDA-capable device 和 Result = PASS；GPU 型号、驱动能力和 Toolkit 版本不同，输出细节也会不同。

WSL 与原生 Linux 的边界

这套流程只适用于 WSL2。原生 Ubuntu 需要按照 CUDA Linux 安装指南先选择受支持的 Ubuntu 版本、gcc 和安装方式，再安装 Linux NVIDIA 驱动与 Toolkit；不能直接套用 WSL-Ubuntu 仓库。原生 Linux 中若只想安装 Toolkit，也要根据官方包说明选择不带驱动的包，并确认驱动与 Toolkit 的兼容关系。

常见故障方向

  • nvidia-smi 失败：先在 Windows 检查驱动和 GPU 支持，再检查 wsl.exe --update 及发行版是否为版本 2；不要在 WSL 内安装 Linux 显示驱动来“补救”。
  • nvcc 找不到：确认 cuda-toolkit 包是否安装，再检查 /usr/local/cuda*/bin 和当前 shell 的 PATH。
  • APT 依赖冲突：检查是否同时启用了 Ubuntu 发行版 CUDA 包、NVIDIA 仓库和其他旧源，保留一条安装路线后再处理依赖。