Yolov5环境配置实战指南：从零搭建ultralytics版本开发环境

1. 为什么你的Yolov5环境总是配置失败？

大家好，我是老张，在AI和计算机视觉领域摸爬滚打了十几年，亲手配置过的开发环境没有一千也有八百次了。今天咱们不聊那些高深的理论，就实实在在地聊聊怎么把Yolov5（ultralytics版本）的环境给稳稳当当地搭起来。我发现很多新手朋友，尤其是刚入门深度学习的同学，一看到环境配置就头疼，照着网上零散的教程操作，结果不是这里报错就是那里版本不对，折腾一整天可能还在原地踏步。

其实，配置Yolov5环境这事儿，说难也难，说简单也简单。难就难在它依赖的库多，而且版本之间环环相扣，一个没对上，整个链条就断了。简单呢，是因为只要你掌握了正确的步骤和避坑方法，整个过程就像搭积木一样，按顺序来，非常顺畅。ultralytics版本的Yolov5是目前社区最活跃、迭代最快的版本，功能强大，但它的环境配置也确实有一些“小脾气”，比如对PyTorch和CUDA版本的特定要求，还有那个让无数人栽跟头的pycocotools。

所以，这篇文章就是为你准备的“避坑指南”。我会把我这些年踩过的坑、总结的经验，用最直白的话告诉你。咱们的目标是：不管你用的是Windows、macOS还是Linux，不管你的电脑有没有独立显卡，都能跟着这份指南，一次成功地把环境跑起来。我们不求快，但求稳，把基础打牢了，后面做训练、做推理才会事半功倍。

2. 搭建前的准备工作：磨刀不误砍柴工

在开始敲命令之前，花几分钟做好准备工作，能帮你省下后面几个小时排查错误的时间。这一步的核心思想就是“知己知彼”。

2.1 检查你的“装备”：系统与硬件

首先，你得清楚自己电脑的底子。打开你的命令行（Windows上是CMD或PowerShell，macOS/Linux上是Terminal）。

查看Python版本：

python --version
# 或者
python3 --version

Yolov5要求Python版本至少是3.6.0，但我强烈推荐使用Python 3.7或3.8。这是经过大量项目验证的“黄金版本”，兼容性最好，能避免很多稀奇古怪的依赖问题。如果你的版本低于3.6，或者你系统里有多个Python版本搞得一团糟，我建议你直接安装一个全新的Python 3.8。

查看显卡和CUDA（如果你有NVIDIA显卡并打算用GPU）： 这是决定你安装哪个版本PyTorch的关键。在命令行输入：

nvidia-smi

这个命令会弹出一个信息表，右上角显示的“CUDA Version”就是你显卡驱动支持的最高CUDA版本。比如显示“CUDA Version: 11.4”，意味着你可以安装CUDA 11.4及以下版本（如11.3， 11.2等）的PyTorch。记下这个数字，我们后面选PyTorch安装包时要严格对应。

注意：这里显示的是驱动支持的CUDA版本，不是你电脑上已经安装的CUDA Toolkit版本。PyTorch的安装包会自带所需版本的CUDA运行时库，所以你通常不需要单独在系统里安装完整的CUDA Toolkit，这能避免复杂的系统环境变量配置，是PyTorch非常友好的一点。

如果你的电脑没有NVIDIA显卡，或者你暂时只想用CPU跑跑看，那也没关系。PyTorch也提供了纯CPU版本的安装包，只是后续训练模型会非常慢，适合先验证环境。

2.2 规划你的“工作间”：理解虚拟环境

很多新手会直接往系统的Python环境里装包，这是大忌！不同项目需要不同版本的库，混在一起很快就会冲突，导致项目A能跑，项目B崩掉。虚拟环境就是为每个项目创建一个独立的、干净的“工作间”。

我首推使用 Conda 来管理环境。它不仅能管理Python包，还能管理Python解释器本身，对于处理复杂的科学计算环境特别拿手。如果你还没安装Anaconda或Miniconda，去官网下载一个Miniconda安装包，它更轻量。

假设我们决定使用Python 3.8，那么创建虚拟环境的命令如下：

conda create -n yolov5 python=3.8

这里的 -n yolov5 指定了环境的名字，你可以叫任何你喜欢的名字，比如 yolo_env。python=3.8 则指定了这个环境里Python的版本。

创建完成后，激活这个环境：

• Windows: conda activate yolov5
• macOS/Linux: source activate yolov5 或 conda activate yolov5

激活后，你会发现命令行的提示符前面多了个 (yolov5)，这表示你已经进入了这个专属的工作间，之后所有pip install的操作都只影响这里，不会污染系统。

3. 核心依赖安装：搞定PyTorch这座大山

环境搭好了，现在该安装最重要的依赖——PyTorch了。这是整个配置过程中最容易出错的一环，咱们慢慢来。

3.1 选择正确的PyTorch和Torchvision版本

Yolov5 (ultralytics) 的 requirements.txt 里写的是 torch>=1.7.0 和 torchvision>=0.8.1。这只是最低要求。为了最好的兼容性和性能，我们应该去PyTorch官网获取当前推荐的稳定版本组合。

打开 PyTorch官网，你会看到一个配置选择器：

1. PyTorch Build: 选择 Stable (稳定版)。
2. Your OS: 选择你的操作系统。
3. Package: 如果你用Conda环境，就选 Conda；如果只用pip，就选 Pip。这里我演示Pip安装，因为它更通用。
4. Language: 选 Python。
5. Compute Platform: 这是关键！
   • 如果你有NVIDIA显卡，并且之前nvidia-smi显示的CUDA版本是11.x，就选择对应的 CUDA 11.x。
   • 如果你的显卡比较新，支持CUDA 12.x，也可以选。但务必与驱动支持的最高版本匹配。
   • 如果没有显卡，就选 CPU。

选择完成后，官网会给出对应的安装命令，比如：

# 例如，对于CUDA 11.8的版本
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

但是！ 对于网络环境不太好的同学，我强烈建议采用原始文章里提到的“手动下载whl文件”的方法，这是最稳、最快的方式。因为PyTorch的安装包很大，直接pip在线安装容易因网络超时失败。

3.2 手动安装的实战操作

我们去PyTorch的官方whl文件仓库找对应的文件。以Python 3.8、CUDA 11.1、Windows系统为例：

1. 访问 https://download.pytorch.org/whl/torch_stable.html。
2. 在页面里按Ctrl+F搜索 cu111（代表CUDA 11.1）和 cp38-cp38m（代表Python 3.8）。
3. 找到类似 torch-1.9.0+cu111-cp38-cp38m-win_amd64.whl 和 torchvision-0.10.0+cu111-cp38-cp38m-win_amd64.whl 的文件。版本号可以选更新的，但torch和torchvision的版本必须匹配（官网选择器给出的就是匹配的）。
4. 下载这两个.whl文件到你的电脑本地目录，比如 D:\Downloads。

然后，在你的(yolov5)虚拟环境下，切换到文件所在目录，执行安装：

# 先安装torch
pip install torch-1.9.0+cu111-cp38-cp38m-win_amd64.whl
# 再安装对应的torchvision
pip install torchvision-0.10.0+cu111-cp38-cp38m-win_amd64.whl

顺序很重要，一定要先装torch，再装torchvision。安装完成后，在Python交互环境里验证一下：

import torch
print(torch.__version__) # 应该输出 1.9.0+cu111
print(torch.cuda.is_available()) # 如果显示True，恭喜你，GPU可用！

看到True，心里这块大石头就算落地了。如果显示False，请回头检查CUDA版本是否匹配，或者你是否安装了CPU版本的PyTorch。

4. 安装剩余依赖与破解“恶魔”pycocotools

核心的PyTorch装好了，剩下的就是按清单装包了。首先，我们需要获取Yolov5的源代码。

4.1 获取代码并安装基础依赖

打开命令行，进入你打算存放项目的目录，比如 D:\Projects，然后克隆仓库：

git clone https://github.com/ultralytics/yolov5
cd yolov5

现在你的当前目录下应该有一个 requirements.txt 文件。直接运行：

pip install -r requirements.txt

这个命令会自动安装matplotlib, numpy, opencv-python, Pillow等一系列基础依赖。这个过程通常比较顺利。但99%的人都会卡在下一个环节——pycocotools。

4.2 解决pycocotools安装报错

requirements.txt 里有一行注释掉的 # pycocotools>=2.0。如果你只需要做目标检测推理，不计算COCO数据集格式的mAP（平均精度），你可以暂时不装它。但如果你想做完整的模型训练和评估，这个库是必须的。

直接 pip install pycocotools 在Windows上几乎百分之百会失败，因为它需要编译C++扩展。错误信息通常和 Microsoft Visual C++ 14.0 或 cython 相关。

我的解决方案（实测有效）：

1. 先安装Cython：这是编译的必需品。在安装pycocotools之前，先 pip install cython。
2. 使用预编译的whl文件（Windows用户福音）： 去这个由热心开发者维护的网站：https://github.com/philferriere/cocoapi。注意，这不是官方仓库，但它提供了为Windows预编译好的pycocotools whl文件。 在仓库的Release页面，找到对应你Python版本和系统架构的.whl文件下载。例如，对于Python 3.8的64位Windows系统，就找 pycocotools-2.0.6-cp38-cp38m-win_amd64.whl。
3. 本地安装：下载后，在命令行进入whl文件所在目录，运行：

   pip install pycocotools-2.0.6-cp38-cp38m-win_amd64.whl
   

   如果一切顺利，你会看到成功的安装信息。

对于macOS和Linux用户，通常直接 pip install pycocotools 在安装好Cython后就能成功，因为系统有现成的编译工具链。如果失败，可能需要安装gcc或cmake等开发工具。

5. 环境验证与快速试跑

所有依赖安装完毕，是骡子是马，该拉出来遛遛了。我们用一个最小的例子来验证环境是否真正可用。

5.1 使用官方模型进行图片推理

Yolov5仓库里自带了一些测试图片和训练好的模型权重。我们用它来做个快速测试。确保你在 yolov5 项目目录下，然后运行：

python detect.py --source data/images --weights yolov5s.pt --conf 0.25

我来解释一下这个命令：

• detect.py: 执行推理的脚本。
• --source data/images: 指定输入源，这里指向仓库自带的示例图片文件夹。
• --weights yolov5s.pt: 指定使用的模型权重。yolov5s.pt是官方提供的最小的、速度最快的模型。运行这行命令时，程序会自动下载这个权重文件（大约14MB），所以你不需要提前手动下载。
• --conf 0.25: 置信度阈值，只显示置信度高于0.25的检测框。

如果环境配置完全正确，你会看到命令行开始输出日志，下载权重，然后进行推理。最终，会在项目目录下生成一个 runs/detect/exp 文件夹，里面保存了带有检测框的图片结果。用图片查看器打开看看，是不是有框框准确地画在了人、自行车等物体上？

5.2 常见验证错误及排查

如果上面那一步报错了，别慌，我们一步步排查：

1. ImportError: No module named ‘xxx’： 这是最常见的错误，说明有依赖库没装上。根据缺失的模块名，直接用 pip install xxx 安装即可。建议重新运行一遍 pip install -r requirements.txt，看看是否有包因网络问题安装失败。

2. CUDA out of memory： 这是GPU内存不足。可以尝试换用更小的模型，比如把 yolov5s.pt 换成 yolov5n.pt（纳米级模型）。或者减少推理时的图片尺寸，添加参数 --imgsz 320（将输入图像缩放为320x320）。

3. 与Torch版本相关的警告或错误： 有些警告可能提示某些功能在你安装的Torch版本中已弃用。只要程序能正常运行，可以暂时忽略。如果出现致命错误，可能需要考虑稍微降低或升高PyTorch版本，回归到更稳定的组合，比如 torch==1.8.0 配 torchvision==0.9.0。

4. OpenCV相关错误： 如果报错与OpenCV（cv2）有关，尝试重新安装指定版本：pip install opencv-python-headless==4.5.5.64。-headless版本去掉了GUI相关的依赖，在服务器环境下更干净。

当你看到检测结果图片成功生成，并且检测效果看起来不错时，你的Yolov5开发环境就已经宣告搭建成功，可以投入正式的学习和项目开发了。这个过程看似步骤不少，但每一步都有其道理，踩过一次坑，以后配置任何Python深度学习环境，你都会游刃有余。记住，耐心和按部就班是搞定环境问题的两大法宝。