计算机视觉 / 系统课时

排查环境安装失败

排查环境安装失败

YOLOv5 环境安装失败通常不是单个包的问题,而是 Python、PyTorch、CUDA 与显卡驱动之间的版本链不兼容。本课给出一套从基础环境到 GPU 验证的固定排查顺序,帮助你快速定位冲突并建立可复现的运行环境。

学习目标

  • 按依赖链顺序定位 Python、驱动、CUDA 和 PyTorch 冲突
  • 使用命令确认当前环境,而不是凭安装记录猜测
  • 修复后完成 CPU 或 GPU 最小验证

先识别失败发生在哪一层

安装错误应按“解释器 → 包管理器 → PyTorch → CUDA → YOLOv5 依赖”的顺序处理。不要一看到报错就反复执行 pip install -r requirements.txt,因为底层版本不匹配时,重复安装只会产生更多冲突。

YOLOv5 环境依赖链与排查顺序

常见现象可以先归类:

现象 优先检查
python 或 pip 找不到 解释器安装、PATH、虚拟环境
包版本无法解析 Python 版本、pip 版本、镜像源
torch.cuda.is_available() 为 False 驱动、PyTorch 安装类型、GPU 可见性
导入时报 DLL 或共享库错误 CUDA 运行库、系统依赖、环境混装
requirements 安装后仍冲突 已安装旧包、多个 Python 环境交叉使用

收集环境信息

先激活准备运行 YOLOv5 的虚拟环境,再执行以下命令。Windows PowerShell 可将 python3 替换为 python。

bash
python3 --version
python3 -m pip --version
python3 -m pip show torch torchvision
nvidia-smi
python3 -c "import torch; print('torch=', torch.__version__); print('cuda_build=', torch.version.cuda); print('cuda_available=', torch.cuda.is_available())"

预期输出

text
Python 3.x.x
pip <VERSION> from <PATH>
Name: torch
Version: <VERSION>
...
NVIDIA-SMI <VERSION>    Driver Version: <VERSION>
torch= <VERSION>
cuda_build= <VERSION_OR_NONE>
cuda_available= True

实际版本和路径会不同。若没有 NVIDIA GPU,nvidia-smi 不存在且 cuda_available=False 属于正常情况,此时应使用 CPU 版 PyTorch。

这里重点确认三件事:命令是否来自同一个虚拟环境、PyTorch 是否成功导入、当前安装的是 CPU 版还是带 CUDA 支持的版本。

按顺序修复版本冲突

先升级当前环境中的安装工具,避免旧版 pip 无法识别新轮子:

bash
python3 -m pip install --upgrade pip setuptools wheel

预期输出

text
Successfully installed pip-<VERSION> setuptools-<VERSION> wheel-<VERSION>

随后卸载可能混装的 PyTorch 包,再根据 PyTorch 官方安装方式选择 CPU 或匹配驱动的 CUDA 构建。下面给出 CPU 环境的完整示例,适合先验证 YOLOv5 代码本身:

bash
python3 -m pip uninstall -y torch torchvision torchaudio
python3 -m pip install torch torchvision torchaudio
python3 -c "import torch; print(torch.__version__); print(torch.rand(2, 2))"

预期输出

text
<VERSION>
tensor([[<VALUE>, <VALUE>],
        [<VALUE>, <VALUE>]])

若必须使用 GPU,不要单独根据本机安装的 CUDA Toolkit 版本判断 PyTorch 包。应先确认显卡驱动能够支持目标 CUDA 运行时,再安装对应的 PyTorch 构建。驱动过旧时,优先升级驱动;不要通过复制 DLL 或共享库文件规避兼容性检查。

重新安装 YOLOv5 依赖并验证

确保终端位于 YOLOv5 项目根目录,再安装依赖:

bash
python3 -m pip install -r requirements.txt
python3 -c "import torch, cv2, numpy; print('environment ok')"

预期输出

text
Successfully installed <PACKAGES>
environment ok

如果安装过程仍提示依赖冲突,可创建全新的虚拟环境,而不是继续修补已经混乱的环境。一个项目只绑定一个解释器,并始终使用 python -m pip 安装包,可以避免 pip 指向其他 Python 的问题。

常见根因与处理

No matching distribution found 通常表示当前 Python 版本、操作系统架构或包版本不受支持。先检查 Python 是否为 64 位,再选择兼容版本,不要强制安装来源不明的 wheel。

ModuleNotFoundError 常见于包安装到了另一个解释器。使用 python3 -m pip show <PACKAGE> 查看安装路径,并与 python3 -c "import sys; print(sys.executable)" 的解释器路径对照。

CUDA 可用性为 False 时,依次确认系统能否执行 nvidia-smi、PyTorch 是否包含 CUDA 构建、容器或远程环境是否暴露 GPU。只安装 CUDA Toolkit 并不能让 CPU 版 PyTorch 自动获得 GPU 能力。

本课总结

  • 环境问题应从 Python 和 pip 开始,逐层检查到 PyTorch、驱动与 CUDA
  • 使用同一解释器执行 python -m pip,可以避免多数环境混装问题
  • 修复后先完成最小导入和张量测试,再继续安装与运行 YOLOv5

下一课预告

下一课将排查数据加载错误,重点处理路径失效、标签缺失、类别越界和损坏图片。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

排查环境安装失败

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通