nvidia-smi命令找不到或无输出，说明nvidia驱动未安装、安装失败或未重启生效；此时pytorch所有cuda检查均无意义，须先在宿主机终端确认驱动状态并重启。
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 用户：安装完也建议重启；若设备管理器中显示“Microsoft 基本显示适配器”，说明驱动未生效，需用 DDU 彻底卸载后重装
torch.cuda.is_available() 返回 False 但 nvidia-smi 正常
说明驱动已就绪，但 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 或 Docker 容器里 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必须存在且可访问
torch.version.cuda 返回 None
说明 CUDA Runtime 未被 PyTorch 正确加载。这时 torch.cuda.is_available() 会静默返回 False，不报错也不提示缺啥。
实操建议：
- 运行 Python 代码：
import torch; print(torch.version.cuda)—— 若输出None，说明 Runtime 未加载 - 检查
LD_LIBRARY_PATH（Linux）或PATH（Windows）是否包含 CUDA Toolkit 的lib64（如/usr/local/cuda-12.1/lib64） - 不要依赖
nvcc --version判断——它只说明编译器存在，不代表运行时可用
nvidia-smi 显示的 CUDA 版本之间是“向上兼容”关系，但 PyTorch 二进制包只能在驱动明确支持的运行时范围内加载；这个边界很硬，没有 fallback，也几乎不报错，最容易被当成“玄学问题”忽略。Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
