计算机视觉 / 系统课时
排查环境安装失败
排查环境安装失败
YOLOv5 环境安装失败通常不是单个包的问题,而是 Python、PyTorch、CUDA 与显卡驱动之间的版本链不兼容。本课给出一套从基础环境到 GPU 验证的固定排查顺序,帮助你快速定位冲突并建立可复现的运行环境。
学习目标
- 按依赖链顺序定位 Python、驱动、CUDA 和 PyTorch 冲突
- 使用命令确认当前环境,而不是凭安装记录猜测
- 修复后完成 CPU 或 GPU 最小验证
先识别失败发生在哪一层
安装错误应按“解释器 → 包管理器 → PyTorch → CUDA → YOLOv5 依赖”的顺序处理。不要一看到报错就反复执行 pip install -r requirements.txt,因为底层版本不匹配时,重复安装只会产生更多冲突。

常见现象可以先归类:
| 现象 | 优先检查 |
|---|---|
python 或 pip 找不到 |
解释器安装、PATH、虚拟环境 |
| 包版本无法解析 | Python 版本、pip 版本、镜像源 |
torch.cuda.is_available() 为 False |
驱动、PyTorch 安装类型、GPU 可见性 |
| 导入时报 DLL 或共享库错误 | CUDA 运行库、系统依赖、环境混装 |
| requirements 安装后仍冲突 | 已安装旧包、多个 Python 环境交叉使用 |
收集环境信息
先激活准备运行 YOLOv5 的虚拟环境,再执行以下命令。Windows PowerShell 可将 python3 替换为 python。
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())"预期输出
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 无法识别新轮子:
python3 -m pip install --upgrade pip setuptools wheel预期输出
Successfully installed pip-<VERSION> setuptools-<VERSION> wheel-<VERSION>随后卸载可能混装的 PyTorch 包,再根据 PyTorch 官方安装方式选择 CPU 或匹配驱动的 CUDA 构建。下面给出 CPU 环境的完整示例,适合先验证 YOLOv5 代码本身:
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))"预期输出
<VERSION>
tensor([[<VALUE>, <VALUE>],
[<VALUE>, <VALUE>]])若必须使用 GPU,不要单独根据本机安装的 CUDA Toolkit 版本判断 PyTorch 包。应先确认显卡驱动能够支持目标 CUDA 运行时,再安装对应的 PyTorch 构建。驱动过旧时,优先升级驱动;不要通过复制 DLL 或共享库文件规避兼容性检查。
重新安装 YOLOv5 依赖并验证
确保终端位于 YOLOv5 项目根目录,再安装依赖:
python3 -m pip install -r requirements.txt
python3 -c "import torch, cv2, numpy; print('environment ok')"预期输出
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
下一课预告
下一课将排查数据加载错误,重点处理路径失效、标签缺失、类别越界和损坏图片。