WSL2 下 NVIDIA 驱动安装后 CUDA 不可用？

Question

在 WSL2 中成功安装 NVIDIA 驱动（如通过 `nvidia-driver-535` 或更高版本）后，`nvidia-smi` 可正常显示 GPU 信息，但 `nvcc --version` 报错“command not found”，或 `python -c "import torch; print(torch.cuda.is_available())"` 返回 `False`，常见原因并非驱动缺失，而是 CUDA Toolkit 未在 WSL2 发行版中独立安装。NVIDIA 官方明确指出：WSL2 的 `nvidia-smi` 依赖宿主机 Windows 端的驱动和 WSL2 GPU 支持（需 Windows 11 22H2+ / Win10 21H2+ + WSL2 1.2.0+），但 CUDA 运行时（`libcudart`）与开发工具（`nvcc`, `cuda-toolkit`）必须**单独在 Linux 子系统内安装对应版本的 `cuda-toolkit-12-x`（如 `cuda-toolkit-12-4`）deb 包**，且需配置 `PATH` 和 `LD_LIBRARY_PATH`。遗漏此步骤、版本不匹配（如宿主机驱动为 535，却装了 cuda-toolkit-11.8）、或误用 Windows 版 CUDA 安装包，均会导致 CUDA 不可用——这是 WSL2 下最典型、最高频的配置陷阱。

Answer 1

```html

一、现象层：表征异常与典型报错

在 WSL2 环境中执行以下命令时出现预期外行为：

• nvidia-smi ✅ 正常输出 GPU 型号、驱动版本（如 535.104.05）及显存状态；
• nvcc --version ❌ 报错 command not found；
• python -c "import torch; print(torch.cuda.is_available())" ❌ 返回 False；
• ls /usr/local/ | grep cuda ❌ 无 cuda-12-x 目录；
• ldconfig -p | grep cudart ❌ 无 libcudart.so 条目。

二、机制层：WSL2 CUDA 架构的双平面模型

NVIDIA 官方定义的 WSL2 GPU 支持本质是「驱动-运行时分离架构」：

组件	宿主机（Windows）	客户机（WSL2 Linux）
GPU 驱动	✅ 必须安装 nvidia-driver-535+（含 WSL2 支持模块）	❌ 不安装驱动，仅通过 libcuda.so 代理调用
CUDA 运行时	无关（Windows CUDA 安装包对 WSL2 无效）	✅ 必须安装匹配的 cuda-toolkit-12-4 deb 包
开发工具链	❌ nvcc, cuobjdump 等不可跨系统使用	✅ 必须在 WSL2 内独立部署并配置 PATH/LD_LIBRARY_PATH

三、诊断层：五步精准归因流程

graph TD
  A[观察 nvidia-smi 成功] --> B{检查 nvcc 是否存在}
  B -->|否| C[确认 cuda-toolkit 是否已 apt 安装]
  B -->|是| D[验证 cuda-toolkit 与驱动兼容性]
  C --> E[检查 /usr/local/cuda-12-4 是否存在]
  E --> F[确认 /usr/local/cuda 软链接指向正确版本]
  F --> G[验证 LD_LIBRARY_PATH 是否包含 /usr/local/cuda/lib64]
  G --> H[测试 libcudart 加载：ldd $(which nvcc) | grep cudart]
  H --> I[最终判定：CUDA Toolkit 缺失/错配/路径未生效]

四、实践层：Ubuntu 22.04 下 CUDA-12.4 完整部署

以 NVIDIA 驱动 535 为前提，执行以下原子化操作：

1. 更新源并添加 NVIDIA 官方仓库：
   sudo apt-key adv --fetch-keys https://developer.download.nvidia.com/compute/cuda/repos/wsl-ubuntu/x86_64/3bf863cc.pub && sudo add-apt-repository "deb https://developer.download.nvidia.com/compute/cuda/repos/wsl-ubuntu/$(uname -m)/ /"
2. 安装 CUDA Toolkit 12.4（非 11.x！）：
   sudo apt update && sudo apt install -y cuda-toolkit-12-4
3. 创建符号链接并写入环境变量：
   sudo ln -sf /usr/local/cuda-12-4 /usr/local/cuda
echo 'export PATH=/usr/local/cuda/bin:$PATH' >> ~/.bashrc
echo 'export LD_LIBRARY_PATH=/usr/local/cuda/lib64:$LD_LIBRARY_PATH' >> ~/.bashrc
4. 重载配置并验证：
   source ~/.bashrc && nvcc --version → 应输出 release 12.4, V12.4.127
5. PyTorch 兼容性验证：
   pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124

五、避坑层：高频反模式清单

• 🚫 在 WSL2 中运行 Windows 版 cuda_12.4.1_535.104.05_win11.exe —— 完全无效且污染 PATH；
• 🚫 混用驱动与 Toolkit 版本：535 驱动 最低要求 CUDA 12.2+，不支持 11.8；
• 🚫 忘记 sudo ldconfig 或未将 /usr/local/cuda/lib64 加入 LD_LIBRARY_PATH；
• 🚫 使用 conda install pytorch-cuda=11.8 导致 PyTorch 与系统 CUDA 运行时不一致；
• 🚫 在 WSL2 中执行 nvidia-smi -q 误判为“CUDA 已就绪”，实则仅验证了驱动代理层。

六、演进层：面向生产环境的健壮性加固

针对企业级 AI 开发场景，建议引入以下增强机制：

# 自动化校验脚本（cuda-health-check.sh）
#!/bin/bash
DRIVER_VER=$(nvidia-smi --query-gpu=driver_version --format=csv,noheader)
CUDA_VER=$(nvcc --version 2>/dev/null | awk 'NR==3 {print $6}')
COMPATIBLE=$(nvidia-smi --query-gpu=compute_cap --format=csv,noheader | head -1 | sed 's/\.//')
echo "Driver: $DRIVER_VER | CUDA: $CUDA_VER | Arch: $COMPATIBLE"
[[ "$DRIVER_VER" =~ ^535 ]] && [[ "$CUDA_VER" =~ ^12\.4 ]] && echo "✅ Verified for Ampere+/Hopper" || echo "⚠️ Version mismatch"

```