Ubuntu 下 PyTorch 常见问题与排查指南
一 安装与版本兼容
- 使用受支持的 Python 版本（3.8–3.11）；Ubuntu 24.04 默认可能为 Python 3.12，建议安装 3.10 并通过 alternatives 切换：sudo apt install -y python3.10 && sudo update-alternatives --install /usr/bin/python python /usr/bin/python3.10 1。升级 pip：python -m pip install --upgrade pip。
- 避免 apt 与 pip 混装 导致冲突：sudo apt remove python3-pytorch；pip uninstall torch；随后仅在虚拟环境中用 pip 安装。
- 获取与驱动匹配的 PyTorch 安装命令（优先使用官网命令）。例如 CUDA 11.8：pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118。
- 网络慢或超时可使用国内镜像（安装 CPU 版本时尤有用）：pip install torch torchvision torchaudio -i https://pypi.tuna.tsinghua.edu.cn/simple。
二 GPU CUDA 与驱动
- 用 nvidia-smi 查看驱动与最高可用 CUDA 运行时版本；用 python -c “import torch; print(torch.cuda.is_available())” 验证 PyTorch 是否能用 GPU。
- 若 torch.cuda.is_available() 为 False：优先检查驱动是否安装/过旧、是否安装了与 PyTorch 匹配的 CUDA 版本；必要时重装驱动或改用与驱动匹配的 PyTorch CUDA 版本。
- 注意区分 驱动报告的 CUDA 版本 与 Toolkit 版本；PyTorch 预编译包通常自带所需 CUDA 运行时，无需单独安装完整 Toolkit，关键是版本匹配。
- 老旧显卡可能不被新版本支持，可选择旧版 PyTorch 或改用 CPU 模式。
三 依赖库与虚拟环境
- 常见运行时依赖缺失（如 libgl1、libglib2.0-0、ffmpeg）：sudo apt update && sudo apt install -y libgl1 libglib2.0-0 ffmpeg。
- 推荐在虚拟环境中安装以避免系统级冲突：python -m venv ~/pytorch_env && source ~/pytorch_env/bin/activate && pip install torch。
- 若出现路径冲突或 ModuleNotFoundError，检查解释器与包路径是否一致：which python、which pip；确保安装与运行在同一环境。
- 如使用 VSCode，通过左下角或 Ctrl+Shift+P 选择对应虚拟环境的解释器。
四 常见报错与快速修复
- DataLoader 报 “already started” 或卡住：将 num_workers 设为 0 进行排查（多进程与系统环境相关）。
- TensorBoard 报错：缺少 TensorBoard，安装：conda install tensorboard 或 pip install tensorboard；启动：tensorboard --logdir log --port 41889。
- 类型不匹配 RuntimeError：输入在 CPU 而模型在 GPU，将输入转到 GPU：inputs = inputs.to(device)。
- DataLoader 返回 PIL.Image 导致类型错误：在 Dataset 的 transform 中加入 ToTensor()。
- 权限或编译问题：避免不必要的 sudo pip；源码编译需安装 编译工具链与依赖；必要时设置 LD_LIBRARY_PATH、PATH、CUDA_HOME 等环境变量。
五 验证与性能优化
- 安装后验证：
- 版本：python -c “import torch; print(torch.version)”
- GPU：python -c “import torch; print(‘CUDA available:’, torch.cuda.is_available())”
- 性能优化建议：
- 训练加速：使用 torch.cuda.amp 混合精度；提高 DataLoader 的 num_workers 与预取；合理多卡并行。
- 数据解码：图片可用 turbojpeg/jpeg4py 加速。
- 资源监控：使用 nvidia-smi、htop 观察显存与 CPU/内存占用。
