📚 课程目录第1章 YOLOv5环境搭建与项目初始化

1. YOLOv5 环境搭建与项目初始化

说实话，做计算机视觉这几年，我见过太多同学在环境搭建这一步就卡住了。明明算法原理都懂，代码也能看明白，结果一跑就报错。嗯，这其实很正常。环境配置这东西，说白了就是「细节决定成败」。

我个人习惯是，每开始一个新项目，都会重新梳理一遍环境。别嫌麻烦，这一步做好了，后面能省下大把时间。今天我们就从零开始，把 YOLOv5 的整套环境搭起来。

  本章核心目标： 完成从 Anaconda 安装到 YOLOv5 源码下载、依赖配置的全流程，确保你能在本地跑通第一个检测 demo。

1.1 环境概览：我们需要什么？

先看看整个技术栈长什么样。我画了张图，帮你快速建立全局认知。

你看，整个结构其实很清晰。最底层是 Anaconda 管理 Python 环境，往上依次是 CUDA 加速、PyTorch 框架，最上面才是 YOLOv5 源码。每一层都依赖下一层，所以安装顺序不能乱。

1.2 Anaconda 安装与虚拟环境创建

为什么我坚持用 Anaconda？说白了，就是怕「环境打架」。你想想看，同时做三四个项目，每个项目依赖的 Python 版本、包版本都不一样。没有虚拟环境管理，迟早要出问题。

我曾经有一次，为了复现一个老项目，被迫把系统 Python 从 3.10 降到了 3.7，结果另一个项目直接崩了。从那以后，每个项目我都单独建一个虚拟环境。

安装步骤

下载 Anaconda： 去官网（anaconda.com）下载对应系统的安装包。我建议选 Python 3.9 以上的版本。
安装： 一路默认就行。Windows 用户注意，安装时勾选「Add Anaconda to my PATH environment variable」。
验证安装： 打开终端（或 Anaconda Prompt），输入 conda --version，看到版本号就对了。

创建 YOLOv5 专用环境

# 创建一个名为 yolov5 的环境，指定 Python 3.9
conda create -n yolov5 python=3.9 -y

# 激活环境
conda activate yolov5

# 验证 Python 版本
python --version

我的习惯： 环境名用项目名，方便区分。比如 yolov5、yolov8、yolov10，各占一个环境，互不干扰。

1.3 CUDA 与 cuDNN 安装

这一步很多人会翻车。其实核心就一句话：PyTorch 版本、CUDA 版本、显卡驱动版本，三者必须匹配。

我见过最典型的错误是：装了 CUDA 12.0，结果 PyTorch 只支持到 11.8，最后跑不起来。所以我的建议是——先查 PyTorch 官网，看它支持哪些 CUDA 版本，再决定装哪个。

检查显卡驱动

# Windows
nvidia-smi

# Linux
nvidia-smi

看输出里的 CUDA Version，这是你的驱动支持的最高 CUDA 版本。比如显示 12.1，那你装 CUDA 11.8 或 12.1 都可以。

安装 CUDA

去 NVIDIA 官网下载对应版本的 CUDA Toolkit。
我推荐 CUDA 11.8，兼容性最好，PyTorch 支持也最稳定。
安装时选「自定义安装」，只勾选 CUDA 组件，别装驱动（除非你的驱动太老）。

安装 cuDNN

去 NVIDIA 开发者网站下载 cuDNN，需要注册账号。
选择与 CUDA 版本匹配的 cuDNN 版本。
解压后，把 bin、include、lib 三个文件夹复制到 CUDA 安装目录下。

⚠️ 避坑指南： 我曾经装完 CUDA 后忘了配环境变量，结果 PyTorch 一直检测不到 GPU。检查一下系统环境变量里有没有 CUDA_PATH，没有就手动加上。

1.4 PyTorch 安装

这一步其实最简单。PyTorch 官网有个安装命令生成器，选好你的配置，复制命令就行。

# CUDA 11.8 版本
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

# 如果你没有 GPU，或者想先用 CPU 调试
pip install torch torchvision torchaudio

验证安装

python -c "import torch; print(torch.__version__); print(torch.cuda.is_available())"

输出 True 就说明 GPU 可用。如果输出 False，别慌，检查一下 CUDA 版本是否匹配。

  关键指标对照表：
  
    PyTorch 版本推荐 CUDA 版本Python 版本
2.0.x11.83.8 - 3.11
1.13.x11.7 / 11.83.7 - 3.10
1.12.x11.6 / 11.73.7 - 3.10

PyTorch 版本	推荐 CUDA 版本	Python 版本
2.0.x	11.8	3.8 - 3.11
1.13.x	11.7 / 11.8	3.7 - 3.10
1.12.x	11.6 / 11.7	3.7 - 3.10

1.5 YOLOv5 源码下载与依赖配置

环境搭好了，终于可以下载 YOLOv5 了。我个人习惯用 Git 克隆，这样后续更新方便。

下载源码

# 克隆官方仓库
git clone https://github.com/ultralytics/yolov5.git

# 进入目录
cd yolov5

# 安装依赖
pip install -r requirements.txt

requirements.txt 里包含了所有需要的包，比如 matplotlib、opencv-python、tqdm 等等。安装过程可能会有点慢，耐心等就好。

验证安装

# 下载一个预训练模型
python -c "from utils.downloads import attempt_download; attempt_download('yolov5s.pt')"

# 跑一个简单的检测 demo
python detect.py --weights yolov5s.pt --source data/images/bus.jpg

如果一切顺利，你会看到检测结果保存在 runs/detect/exp 目录下。嗯，到这一步，环境就算彻底搭好了。

小技巧： 第一次跑 detect.py 时，它会自动下载模型文件。如果下载慢，可以手动去 GitHub Releases 页面下载，放到项目根目录。

1.6 常见问题与解决方案

我把这些年遇到的环境问题整理了一下，你遇到类似情况可以直接对照排查。

问题	原因	解决方案
torch.cuda.is_available() 返回 False	CUDA 版本不匹配或驱动太老	更新驱动，或重装匹配的 CUDA
ImportError: No module named 'torch'	没激活虚拟环境	运行 `conda activate yolov5`
pip install 报 SSL 错误	网络问题或代理设置	加 `--trusted-host pypi.org --trusted-host files.pythonhosted.org`
运行 detect.py 报显存不足	模型太大或 batch size 太大	用 `--device cpu` 或减小 `--batch-size`

说实话，环境搭建这件事，第一次做确实有点烦。但只要你按照这个流程走一遍，后面再搭其他项目就轻车熟路了。我每次开新课、换新机器，都是这套流程，从来没出过问题。