Ubuntu 上 PyTorch 安装错误排查与修复指南
一 环境准备与快速自检
- 更新系统并安装基础工具：sudo apt update && sudo apt install -y python3 python3-pip
- 建议使用虚拟环境隔离依赖：python3 -m venv ~/pytorch_env && source ~/pytorch_env/bin/activate
- 检查版本：python3 --version、pip3 --version；必要时升级 pip：python -m pip install --upgrade pip
- 验证安装：python - <<‘PY’
import torch
print(“torch:”, torch.version)
print(“cuda:”, torch.cuda.is_available())
PY
以上步骤能快速定位是否为环境或版本导致的问题。
二 常见错误与对应修复
- 找不到匹配版本或哈希不匹配
- 升级 pip：python -m pip install --upgrade pip
- 使用国内镜像并延长超时：pip install torch torchvision torchaudio -i https://pypi.tuna.tsinghua.edu.cn/simple/ --default-timeout=1000
- 若仍失败，尝试带哈希的官方通道或指定版本：pip install torch== torchvision== torchaudio== -f https://download.pytorch.org/whl/torch_stable.html
- 权限错误
- 避免使用 sudo 安装到系统目录，优先在虚拟环境内安装；或在用户目录安装：pip install --user torch …
- apt 与 pip 版本冲突
- 若曾用 apt 安装过 PyTorch，先卸载：sudo apt remove python3-pytorch；随后仅在虚拟环境用 pip 安装
- 运行时缺少系统依赖（常见于导入 torchvision/多媒体）
- 安装缺失库：sudo apt install -y libgl1 libglib2.0-0 ffmpeg
- Python 版本不兼容
- Ubuntu 24.04 可能默认 Python 3.12，而部分 PyTorch 版本仅支持 3.8–3.11。可安装适配版本并切换：sudo apt install -y python3.10 && sudo update-alternatives --install /usr/bin/python python /usr/bin/python3.10 1
- 网络不稳定导致超时
- 使用镜像源并加大超时：pip install … -i https://pypi.tuna.tsinghua.edu.cn/simple/ --default-timeout=1000
以上对应措施覆盖最常见的报错场景，可逐项尝试。
三 GPU 与 CUDA 相关错误
- 驱动与工具链核对
- 查看驱动/CUDA 运行时：nvidia-smi（右上显示 Supported/Runtime CUDA）
- 查看工具链：nvcc --version（若未安装，可 sudo apt install nvidia-cuda-toolkit）
- 注意：nvidia-smi 显示的 CUDA 为驱动支持上限；实际安装的 PyTorch 需与之匹配或使用对应的预编译包
- 安装匹配版本的 PyTorch
- 无 GPU 或仅需 CPU：pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu
- 有 GPU（示例为 CUDA 11.8）：pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118
- 使用 conda（示例）：conda create -n pytorch_env python=3.10 -c conda-forge && conda activate pytorch_env && conda install pytorch torchvision torchaudio pytorch-cuda=11.8 -c pytorch -c nvidia
- 验证 GPU 可用
- python - <<‘PY’
import torch
print(“cuda available:”, torch.cuda.is_available())
print(“device count:”, torch.cuda.device_count())
print(“current device:”, torch.cuda.current_device())
print(“device name:”, torch.cuda.get_device_name(0) if torch.cuda.is_available() else “N/A”)
PY
若仍不可用，优先检查驱动与 PyTorch 的 CUDA 版本是否一致，再检查环境变量与虚拟环境路径是否一致。
四 一键最小复现流程
- CPU 环境
- python3 -m venv ~/venv && source ~/venv/bin/activate
- python -m pip install --upgrade pip
- pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu
- python - <<‘PY’
import torch
print(“torch:”, torch.version, “cuda:”, torch.cuda.is_available())
PY
- GPU 环境（示例 CUDA 11.8）
- python3 -m venv ~/venv && source ~/venv/bin/activate
- python -m pip install --upgrade pip
- pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118
- 运行上面的 Python 验证段；若失败，核对 nvidia-smi 与 pip 安装的 CUDA 标签是否一致
该流程覆盖大多数用户环境，便于快速定位问题所在。
