nvidia-smi命令找不到或无输出说明nvidia驱动未安装、安装失败或未重启生效，这是最底层的失败信号；必须在宿主机终端运行，linux需下载≥535.x驱动并sudo reboot，windows需重启或用ddu彻底重装。
nvidia-smi 命令找不到或无输出
这是整个链路最底层的失败信号，说明 NVIDIA 驱动压根没装、安装失败，或未重启生效。PyTorch 后续所有检查都无意义。
常见错误现象：nvidia-smi 报 bash: nvidia-smi: command not found，或执行后空白、卡住、提示 No devices were found
- 必须在宿主机终端（不是 Docker 容器、不是 WSL2 子系统内部）直接运行
nvidia-smi - Linux 用户：去 NVIDIA 官网下载匹配显卡型号和系统的驱动（2026 年推荐 ≥535.x），安装后务必执行
sudo reboot—— 驱动模块需内核重载 - Windows 用户：安装完也建议重启，避免 WDDM 模式干扰 CUDA 计算；若设备管理器中显示“Microsoft 基本显示适配器”，说明驱动未生效，需用 DDU 彻底卸载后重装
nvidia-smi 能用但 torch.cuda.is_available() 返回 False
说明驱动已就绪，但 PyTorch 与底层 CUDA 运行时不匹配。关键不是 nvcc --version，而是 nvidia-smi 右上角显示的 CUDA Version: X.Y —— 它代表当前驱动**能支持的最高 CUDA 运行时版本**。
例如：nvidia-smi 显示 CUDA Version: 12.4，但你装了为 cu125 编译的 PyTorch 2.5，就会静默失败；PyTorch 2.5 官方仅支持 cu118 和 cu121（截至 2026 年 4 月）
- 查清你驱动支持的最高 CUDA 版本：驱动 ≥525.x → 可跑
cu118；≥535.x → 可跑cu121 - 确认 PyTorch 是否带 CUDA 支持：运行
python -c "import torch; print(torch.__version__)"，输出中必须含+cu118或+cu121，否则就是 CPU 版本 - 重装时务必指定官方源：
pip install torch==2.5.0 --index-url https://download.pytorch.org/whl/cu121
WSL2 或容器中 GPU 不可见
WSL2 本身不直连 GPU，依赖 Windows 宿主机驱动透传；Docker 容器则依赖 --gpus all 和设备节点挂载。两者都容易漏掉关键启动参数。
常见错误现象：nvidia-smi 在 WSL2 终端中报错或无输出；docker run 启动后 torch.cuda.is_available() 仍为 False
- WSL2：Windows 端驱动必须 ≥470.14，且执行
wsl --update --web-download+wsl --shutdown；然后在 WSL2 中运行nvidia-smi成功，才可继续装 PyTorch - Docker：启动容器时必须加
--gpus all，不能只靠LD_LIBRARY_PATH或CUDA_HOME；宿主机的/dev/nvidiactl、/dev/nvidia-uvm、/dev/nvidia0必须被正确挂载 - 环境变量
CUDA_VISIBLE_DEVICES若设为-1或空字符串，也会导致torch.cuda.device_count()返回 0
torch.version.cuda 输出 None
说明 PyTorch 找不到 CUDA 运行时库（如 libcudart.so），但不会报错，只会让 is_available() 静默返回 False。这在自定义镜像或手动部署环境中高频出现。
注意：nvcc --version 能用 ≠ 运行时可用；它只说明编译器存在，不代表 lib64 路径已加入动态链接器搜索范围
- Linux 下检查：
echo $LD_LIBRARY_PATH是否包含 CUDA Toolkit 的lib64目录（如/usr/local/cuda-12.1/lib64） - 若缺失，临时修复：
export LD_LIBRARY_PATH=/usr/local/cuda-12.1/lib64:$LD_LIBRARY_PATH - 容器或 WSL2 中，不要假设
/usr/local/cuda是软链到正确版本；最好显式指定完整路径，比如/usr/local/cuda-12.1
nvidia-smi 能跑，但忘了 wsl --shutdown 强制重载设备节点。这些细节不验证，光重装 PyTorch 十次也没用。Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
