Ubuntu 上 PyTorch 常见问题与排查清单
一 安装与版本兼容
- 使用受支持的 Python 版本（建议 3.8–3.11）；Ubuntu 24.04 默认可能是 Python 3.12，会导致安装失败或不兼容。建议安装 python3.10 并通过 alternatives 切换默认版本。
- 升级 pip 到最新版本，避免无法识别新 wheel 包。
- 避免 apt 与 pip 混装 造成冲突：若用 apt 装过旧版，先卸载再统一用 pip 安装。
- 安装命令示例（以 CUDA 11.8 为例）：pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118。
- 若遇到网络超时，可临时使用国内镜像源（如清华源）加速安装。
- 验证安装：
- 查看版本：python -c “import torch; print(torch.version)”
- 检查 CUDA：python -c “import torch; print(torch.cuda.is_available())”。
二 GPU CUDA 与驱动
- 区分 nvidia-smi 显示的驱动/CUDA 运行时版本 与 nvcc 显示的 CUDA Toolkit 版本，二者不一致是常见问题；安装 PyTorch 时应以 PyTorch 官方提供的 预编译 CUDA 版本 为准，避免自行混装过多 CUDA 组件。
- 若 torch.cuda.is_available() 为 False：
- 检查驱动是否安装并加载：nvidia-smi 是否能正常显示 GPU 与驱动版本。
- 确认安装的 PyTorch 是 GPU 版本（如 cu118/cu121 等），而非 CPU 版。
- 避免用系统 apt 的 nvidia-cuda-toolkit 与 pip 安装的 PyTorch 产生冲突，优先使用 PyTorch 官方 whl。
- 老显卡或驱动过旧时，可能无法使用最新 CUDA 版本的 PyTorch，需选择与之匹配的旧版 PyTorch 或改用 CPU 模式。
三 依赖库与运行错误
- 常见运行时依赖缺失（多见于导入 torchvision、ffmpeg、OpenGL 相关）：
- 安装：sudo apt update && sudo apt install -y libgl1 libglib2.0-0 ffmpeg。
- 常见报错与修复：
- RuntimeError: Input type (CPU) and weight type (CUDA)：将输入张量或模型统一到同一设备（如 tensor.to(‘cuda’) 或 model.to(‘cuda’)）。
- DataLoader 报 “already started” 或 num_workers>0 异常：先设 num_workers=0 排查环境问题，再逐步恢复。
- TensorBoard 报错：缺少 tensorboard/Python summary writer，执行 conda/pip 安装后使用 tensorboard --logdir <log_path> 启动。
- 类型不匹配：Dataset 未将图像转为张量，需在 transform 中加入 ToTensor()。
四 虚拟环境与权限
- 优先使用 venv/conda 隔离环境，避免系统包污染：
- venv 示例：python -m venv ~/pytorch_env && source ~/pytorch_env/bin/activate && pip install torch。
- conda 示例：conda create -n pytorch_env python=3.10 && conda activate pytorch_env && conda/pip 安装对应版本。
- 在 VS Code 中切换解释器：Ctrl+Shift+P → Python: Select Interpreter → 选择虚拟环境中的 python。
- 权限问题：不建议用 sudo pip 全局安装，优先在用户目录或虚拟环境内安装；必要时检查目录权限或使用 --user。
五 快速排查清单
- 核对环境：which python / which pip；确保安装和运行在同一虚拟环境。
- 核对版本：python -c “import torch; print(torch.version)” 与 torch.cuda.is_available()。
- 核对驱动与工具链：nvidia-smi、nvcc --version；必要时仅保留一套 CUDA 方案。
- 核对命令来源：优先使用 PyTorch 官网 对应系统/版本/包管理器的安装命令。
- 复现最小示例：
- import torch; print(torch.version, torch.cuda.is_available())
- x = torch.randn(2,3).cuda(); print(x.device)
- 仍异常时：清理并重装（pip uninstall torch torchvision torchaudio → 重新安装），保留完整报错日志以便定位。
