简介：《YOLOv5搭建与目标检测详解》面向具备一定 Python 与计算机视觉基础的入门级研究人员和工程技术人员，聚焦本地环境部署这一常见门槛，从系统要求、依赖安装到模型推理与自定义训练给出可循路径。内容围绕 Windows、macOS 或 Linux 下的环境准备展开，涉及 Python 版本、CUDA 与 cuDNN 的匹配要求，以及 PyTorch 安装、虚拟环境创建、官方源码获取、示例检测脚本中权重与输入尺寸、置信度和 NMS 阈值等参数设置、结果目录查看等环节，末尾延伸到按自有数据集调整配置文件并启动训练的进阶做法。压缩包仅含 1 个 docx 文档，约 19KB，体量轻巧，适合作为随查随用的操作备忘录与教学讲义。已有 239 人学习下载，读者可据此独立完成环境搭建、跑通首个检测实例，并理解后续定制训练的基本流程与排错思路。

1. 版本先定死：YOLOv5 环境为什么老在装的时候翻车

装 YOLOv5 做目标检测，整套骨架其实就四样：Python、PyTorch、CUDA、cuDNN。骨架搭对，后面 clone 仓库、装依赖、下权重都是顺水推舟；骨架错一位，报错能从环境检查一路串到检测脚本。最常见的一幕是：conda 环境里 Python 是 3.10，nvidia-smi右上角写着 CUDA Version 12.x，照着教程敲一句pip install torch torchvision，装完torch.cuda.is_available()返回 False，detect.py 默默退回 CPU，一张 416 的图跑十几秒。更玄学的是同一条命令，别人机器上飞快，你这台就是不行，差别全在驱动版本和 wheel 包是否匹配。下面这套流程按 Windows 11 + RTX 30 系实机走过一遍，Linux 和 macOS 对照改路径即可，新手从第 2 章顺着敲，熟手可以直接跳第 3 章和第 5 章。

2. 环境准备：Anaconda 建 yolov5_env 与 Python 3.8 的取舍

2.1 装 Anaconda：路径别带中文，装完先验 conda 是否在 PATH 里

Anaconda 是可选项，但对第一次搭 PyTorch 环境的人来说基本等于后悔药。直接往系统 Python 里pip install，装崩了想回滚只能一个个卸载，装了 conda 至少能conda env remove -n yolov5_env一键删干净重来。下载安装包时选对应系统的 64 位图形安装器即可，安装过程中有两个地方要留意。

第一是安装路径。我一般会装在D:\Anaconda3这种纯英文、无空格的位置。中文路径在后续 pip 编译、opencv 读写文件时是最容易翻车的隐藏雷，报错信息还往往指向别处，排查起来像拆黑匣子。第二是安装向导最后那页的两个勾选项，「Add Anaconda3 to my PATH environment variable」官方不推荐勾（怕覆盖系统里其他 Python），但对单人开发机来说勾上省事，不勾也行，后面用 Anaconda Prompt 打开终端效果一样。

装完打开终端验证，命令行能返回版本号就说明 conda 可用：

# 查看 conda 版本，确认命令可用 conda --version # 查看当前所有环境，带 * 的是激活中的那个 conda env list

conda --version返回conda 23.x.x之类的字符串即可。conda env list里那个带星号的base是默认环境，后面所有操作都不要在 base 里做，这是我们建独立环境的原因：YOLOv5 的依赖版本跨度大，跟 base 里已有的包很容易打架。

如果终端提示conda : 无法将"conda"项识别为 cmdlet...，说明 PATH 没配上。这种情况不用重装，打开「Anaconda Prompt」这个专用终端就能正常用，或者手动把安装路径\Scripts和安装路径\condabin加进系统环境变量，加完必须重开终端才生效。

2.2 创建 yolov5_env：为什么锁 Python 3.8 而不是 3.10

创建虚拟环境的命令本身很短，但python=3.8这个数字值得单独说一下：

# 创建名为 yolov5_env 的虚拟环境，指定 Python 3.8 conda create --name yolov5_env python=3.8 -y # 激活环境，后续所有安装都在这个环境里做 conda activate yolov5_env

--name后面是环境名，起什么都可以，但建议固定成yolov5_env，这样对照各种教程时不会搞混。-y表示跳过确认提示，省一次回车。python=3.8是硬约束，conda 会自动去匹配 3.8 系列的最新小版本（比如 3.8.18）。

为什么是 3.8？项目原文给的最低要求是 Python 3.6 以上，3.6 和 3.7 现在装很多 wheel 已经找不到预编译包了，只能现场编译，Windows 上大概率卡在Building wheel for xxx。3.10 及以上虽然新，但 YOLOv5 v5.0 那个时期的依赖（尤其是某些版本的thop、pycocotools）对高版本 Python 的预编译轮子覆盖不全，一样容易掉进编译坑。3.8 是这批依赖预编译包覆盖最完整的区间，属于「不新但最省事」的折中。如果你手上的项目明确要用新版 YOLOv5，再考虑往 3.9、3.10 走。

激活成功后，命令行提示符前面会出现(yolov5_env)。这一步一定要肉眼确认，后面所有pip install都依赖这个前缀——忘记激活是新手最高频的翻车点，装了半天全装进 base，跑脚本时照样ModuleNotFoundError。

2.3 环境自检：三行命令确认 pip 和 python 是同一个解释器

环境激活后别急着装包，先确认解释器指向：

# Windows 查看当前 python 可执行文件位置 where python # Linux / macOS 用 which which python # 确认 pip 也指向同一环境 pip -V

where python的输出里应该能看到Anaconda3\envs\yolov5_env\python.exe这一段。pip -V的输出同理，路径里也要带yolov5_env。如果 pip 指向的是AppData\Roaming\Python或者系统 Python 目录，说明存在多个 pip 抢占 PATH 的情况，后续装包会装错地方。常见做法是在环境内强制用python -m pip代替裸pip，能绕开绝大多数的路径错位：

# 用当前 python 解释器自带的 pip，避免装错环境 python -m pip install --upgrade pip

这一句顺手把环境内的 pip 升到最新，老版本 pip 在解析依赖时对 wheel 标签的判断偶尔会出岔子，升级成本几乎为零。

3. 装 PyTorch：CUDA 11.3 轮子与 CPU 回退的两种装法

3.1 选轮子前先看驱动：nvidia-smi 输出里只有右上角那个数字有用

PyTorch 的安装命令取决于你的硬件和驱动，判断依据是nvidia-smi：

# Windows 在 CMD / PowerShell 里直接执行，Linux 同 nvidia-smi

输出是一张表格，重点看两处。右上角有一行CUDA Version: 11.7之类的字样，这是驱动支持的最高 CUDA 运行时版本，不是你已经装的 CUDA 版本，很多人在这里理解偏了。左上角的Driver Version是驱动号。判断规则很简单：我们要装的 PyTorch 轮子所带的 CUDA 版本，必须小于等于右上角这个数字。项目要求里写的是 CUDA 10.2 以上、cuDNN 7.6 以上，只要你的驱动显示 11.x 且不低于 11.3，就可以走 cu113 的轮子。

这里有个容易忽略的点：用 pip 装 PyTorch 的 CUDA 版本，不需要你在系统里单独安装 CUDA Toolkit 和 cuDNN，官方 wheel 包里已经把对应的运行时库打进去了。系统里装 Toolkit 是给需要编译自定义算子的人用的，普通训练和推理场景纯属多余，装完反而可能因为多个 CUDA 版本共存导致LD_LIBRARY_PATH打架。这条认知差异能省掉一大半安装时间。

如果nvidia-smi报「不是内部或外部命令」，说明驱动没装或者没进 PATH，去显卡厂商页面下对应型号的驱动装一下重启即可，这一步绕不过去。

3.2 两条安装命令：cu113 轮子和纯 CPU 版本

确认驱动没问题后，进到激活的yolov5_env里执行。项目原文给的是pip install torch torchvision，这条命令本身没错，但它会去默认源拉最新版，很可能给你装上一个 CUDA 11.8 甚至 12.x 的轮子，跟 11.3 的环境对不上，或者干脆给你一个 CPU 版。稳妥的做法是指定官方 wheel 索引：

# CUDA 11.3 版本，索引地址限定后 pip 只在这个索引里挑 pip install torch torchvision --index-url https://download.pytorch.org/whl/cu113 # 纯 CPU 版本，没有独显或者只想先跑通流程时用 pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu

--index-url的作用是把包来源整个换成 PyTorch 官方的 wheel 仓库，只有这个仓库里才有带+cu113后缀的编译版本。如果不加这个参数，pip 会去公共源找同名包，拿到的通常是 CPU 版或者更高 CUDA 版本。原文里提到的cpuonly是 conda 渠道的包名，用 pip 装的时候不需要它，直接走上面第二条命令就行。

有两点需要说明。一是这条命令不写死版本号，由 pip 挑当前索引里最新的兼容版本；如果你想固定版本，把包名写成torch==x.y.z+cu113的形式，具体版本号从索引页上抄，别照抄别人的博客——索引会随版本更新变化。二是网络慢导致下载中断时会留下半包，重试前先pip cache purge清一下缓存，否则可能一直卡在同一个坏包上。

装完再补一个运行期依赖，项目里 detect.py 的进度条和部分工具函数会用到：

# 补装常用依赖，避免后续脚本 import 时报缺包 pip install numpy opencv-python pillow pyyaml tqdm matplotlib

这条不是必须，第 4 章装requirements.txt时会一起覆盖，先手装一遍的好处是能把错误尽早暴露在这个环节，而不是等到一堆依赖装完才报错。

3.3 装完立刻自检：六行脚本看清 torch 到底认没认到显卡

装完不看一眼就用，等于把问题往后拖。新建一个check_env.py：

import torch # 打印 torch 版本，确认装的是哪个轮子 print("torch:", torch.__version__) # 显卡是否可用，False 说明装成了 CPU 版或驱动不匹配 print("cuda available:", torch.cuda.is_available()) # 可用显卡数量 print("device count:", torch.cuda.device_count()) # torch 编译时链接的 CUDA 版本 print("cuda version:", torch.version.cuda) # cuDNN 版本，None 表示没启用 print("cudnn version:", torch.backends.cudnn.version())

运行python check_env.py。理想输出是cuda available: True，cuda version显示11.3，cudnn version显示一个数字。如果cuda available是 False，先别怀疑显卡坏了，按顺序排查三件事：驱动版本是否够、装的是不是带+cu113后缀的轮子、torch.version.cuda是不是 None。torch.version.cuda为 None 基本可以确诊装成了 CPU 版，卸载重装：

# 卸载干净的写法，避免残留旧版本干扰 pip uninstall -y torch torchvision

如果cuda available是 True 但 cudnn version 是 None，一般是显卡算力与当前轮子不匹配，多见于很老的显卡，这时换 CPU 版本跑通流程反而更快。

4. 拉仓库装依赖：git clone 之后 requirements.txt 怎么装才不打架

4.1 克隆与目录结构：先认识三个文件再动手

环境就绪，把代码拉下来。原项目仓库地址是公开的，命令行直接拉：

# 克隆仓库到当前目录 git clone https://github.com/ultralytics/yolov5.git # 进入项目目录，后面所有命令都在这个目录下执行 cd yolov5

没有装 git 的话，去官网下个安装包，一路默认选项即可；或者直接在仓库页面下载 zip 解压，效果一样，只是后续想切分支会麻烦些。拉下来之后先别急着装依赖，花两分钟认一下目录：detect.py是推理入口，train.py是训练入口，requirements.txt是依赖清单，models/下放网络结构 yaml（比如yolov5s.yaml），data/下放数据集配置 yaml，utils/是工具函数。第 5 章的坑和第 6 章的验证都会回到这几个路径上。

有个细节值得留意：git clone默认拉的是主分支最新代码，而项目文里提到的权重链接指向 v5.0 版本。两者大体兼容，但如果遇到某个参数报unrecognized arguments，很可能就是代码版本和教程对不上。需要固定版本时可以切标签：

# 查看仓库所有标签，确认要用的版本号 git tag # 切到指定版本，标签名从上一句输出里抄 git checkout v5.0

git tag会列出一串v5.0、v6.0、v7.0之类的标签。新手建议先不切，用主分支跑通再说；老项目复现实验时再切，因为切完requirements.txt的依赖约束也会跟着变，等于重新装一遍。

4.2 requirements.txt 逐项过：两行必须删、几行可以缓

这一步是整篇里最容易翻车的地方。先看一眼文件内容：

# 查看依赖清单，Windows 用 type cat requirements.txt

清单里通常包含matplotlib、numpy、opencv-python、pillow、pyyaml、requests、scipy、torch、torchvision、tqdm、pandas、seaborn、thop这些。这里的关键在于torch和torchvision这两行——它们带的版本约束通常是个下限（比如>=1.8.0），直接执行pip install -r requirements.txt，pip 会认为你之前装好的 cu113 版本满足条件，理论上不动它；但只要它判断需要升级，就会从公共源拉一个新版本，把你的 GPU 轮子覆盖成 CPU 版或 CUDA 版本不匹配的包，第 3 章的验证全部白做。

我的习惯是先把这两行注释掉再装：

# 把 torch 和 torchvision 两行前面加 # 注释掉，再执行安装 # 具体行号按文件内容来，别死记 pip install -r requirements.txt

注释掉之后，pip 只会装其余的辅助包，已经装好的 GPU 版 torch 不受影响。装完再跑一次check_env.py确认cuda available还是 True，这个习惯能从根上避免「装完依赖显卡就消失了」这一类问题。

另一个高频卡点是opencv-python。在某些 Python 版本组合下，pip 找不到预编译轮子会去源码编译，Windows 上直接报缺少 C++ 构建工具。遇到这种情况，先在清单里把opencv-python换成opencv-python-headless（无 GUI 依赖，体积小、轮子覆盖更好），或者单独指定一个明确版本安装。Linux 服务器上无桌面的场景，本来就该用 headless 版。

网络慢的话给 pip 指定国内镜像源能快不少：

# 使用镜像源加速，只对本次安装生效 pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

-i参数只影响这一次命令，不会改全局配置，适合临时用。想长期生效就写进pip.ini或~/.pip/pip.conf，但注意配了镜像源之后，第 3 章那种指定--index-url的命令要放后面执行，否则会被镜像源覆盖导致找不到 cu113 轮子。

4.3 预训练权重：yolov5s.pt 的两种拿法和放置位置

依赖装好，需要一个权重文件才能跑推理。项目原文用的是 v5.0 的yolov5s.pt：

# Linux / macOS 有 wget 的情况 wget https://github.com/ultralytics/yolov5/releases/download/v5.0/yolov5s.pt

Windows 自带的 PowerShell 里通常没有 wget，硬敲会报「无法将 wget 项识别为 cmdlet」。两个替代方案，一是用 curl（Win10 1803 之后系统自带）：

# curl 的 -L 跟随重定向，-o 指定输出文件名 curl -L -o yolov5s.pt https://github.com/ultralytics/yolov5/releases/download/v5.0/yolov5s.pt

-L不能省，GitHub 的下载链接会跳转，少了它下回来的是个几百字节的网页而不是模型文件。判断方法很简单：yolov5s.pt正常大小在 14MB 上下，如果你下下来的文件只有几 KB，八成就是这个问题。

二是直接用浏览器打开链接下载，再手动拖进yolov5目录。权重文件放哪都行，--weights参数支持相对路径和绝对路径，但路径里不要有中文和空格，这是后面第 5 章要展开的一个坑。我一般就放在项目根目录下，跟detect.py平级，命令行写起来最短。

yolov5s里的 s 指 small，是这一系列里最小最快的；同系列还有 m、l、x，体积和精度依次上升。第一次跑通流程用 s 就够了，别一上来就下 x，权重几百 MB，加载慢，出问题时也不好判断是环境问题还是模型问题。

5. 常见排查：五个让 detect.py 直接退出的坑

5.1 现象：ModuleNotFoundError: No module named 'torch'，但明明装过

现象：终端里pip list能看到 torch，python detect.py却报找不到模块。

原因：pip 和 python 不是同一个解释器。最常见的是终端关掉重开后 conda 环境没激活，python回落到了系统解释器；另一种是装包时忘了conda activate，全装进 base 了。

解决：先conda activate yolov5_env，再where python和pip -V对比路径是否都带yolov5_env。不一致就统一改用python -m pip install xxx的写法，让 pip 强制跟随当前 python。已经装错环境的包不用管，删环境重来比逐个卸载快：

# 删掉环境重建，比逐个卸载干净 conda deactivate conda env remove -n yolov5_env conda create --name yolov5_env python=3.8 -y conda activate yolov5_env

5.2 现象：装完 requirements.txt，torch.cuda.is_available() 变成 False

现象：第 3 章验证时还是 True，装完依赖再跑一次变 False，或者 detect.py 输出里提示Using CPU。

原因：requirements.txt里的torch >= x.x.x触发了 pip 的重新解析，从公共源拉了一个新的 torch 覆盖掉原来的 cu113 轮子。公共源上的默认版本往往是 CPU 版或更高 CUDA 版本。

解决：按 4.2 的做法先把torch、torchvision两行注释掉再装依赖。已经覆盖了的，重新执行第 3 章的 cu113 安装命令即可，不用重装整个环境：

# 重新装回 GPU 轮子，注意索引地址 pip install torch torchvision --index-url https://download.pytorch.org/whl/cu113 --force-reinstall

--force-reinstall会强制覆盖已装版本，适合这种被误覆盖的场景。装完立刻跑一遍check_env.py，别等跑到一半才发现。

5.3 现象：pip install 卡在 Building wheel for xxx 十几分钟不动

现象：安装停在Building wheel for opencv-python或thop这类包上，CPU 风扇狂转，最后报一堆编译错误。

原因：当前 Python 版本没有对应的预编译 wheel，pip 退回源码编译，而 Windows 上通常缺 Visual C++ Build Tools，Linux 上缺python3-dev。

解决：优先换包而不是装编译器。opencv-python换opencv-python-headless，thop单独装一个明确版本。真要编译的话，Windows 装 Build Tools，Linux 装build-essential和python3-dev。另一个思路是把 Python 降到 3.8，预编译覆盖最全，这也是第 2 章锁 3.8 的实际原因。

5.4 现象：CUDA out of memory，或者 WinError 1455 页面文件太小

现象：detect.py 跑到一半报显存不足退出；Windows 上有时报[WinError 1455] 页面文件太小，无法完成操作。

原因：--img给得太大、--batch-size太高，或者同时开了浏览器、IDE 占着显存。WinError 1455 是系统虚拟内存不够，加载大权重时触发。

解决：先把--img从 640 降到 416 试，再把--batch-size设成 1，用--device 0显式指定单卡。跑通了再往上加，一次只改一个参数，否则出了错不知道是哪个引起的。WinError 1455 去系统设置里把虚拟内存调大，或者干脆重启一次机器释放资源：

# 先降到最小配置跑通，再逐个往上加 python detect.py --weights yolov5s.pt --source test.jpg --img 416 --batch-size 1 --device 0

5.5 现象：结果图保存失败，或报 UnicodeEncodeError

现象：终端里检测框打印出来了，但runs/detect/exp目录下没有图片；或者直接抛编码错误；又或者图片路径里有中文，报文件不存在。

原因：项目路径或图片路径含中文、空格，opencv 的imread/imwrite在部分版本上对非 ASCII 路径支持不好，静默返回 None。

解决：把整个项目挪到纯英文路径，比如D:\work\yolov5，待检测的图片也放到同目录下，文件名改成test.jpg这种。这一条几乎能解决所有「检测结果看不见」的诡异问题。另外输出目录默认是runs/detect/exp，第二次跑会生成exp2、exp3往上递增，找不到结果时先ls runs/detect看一眼实际目录名，别死盯 exp。

6. 跑通验证：detect.py 的四个参数与结果自查

环境、依赖、权重都齐了，跑一条最小命令验证整条链路：

# 用 416 输入尺寸、0.4 置信度跑单张图 python detect.py --weights yolov5s.pt --source test.jpg --img 416 --conf 0.4 --iou 0.5

四个参数的含义和调法值得掰开说。--weights指权重路径，写相对路径时相对的是当前工作目录，不是detect.py所在目录，所以一定要在yolov5目录下执行。--source除了图片，还能填目录、视频文件，填0表示调摄像头。--img是推理时的输入尺寸，必须是 32 的整数倍，416 比默认的 640 快不少，小目标多的场景再往回调大。--conf是置信度阈值，调低会出更多框也更多误检，调高会漏检，0.25 到 0.5 之间是常用区间；--iou控制非极大值抑制的合并力度，密集物体场景调低一点能保留更多相邻框。

几个常用的补充参数：--device 0强制走第一张显卡，--save-txt把检测框坐标另存成 txt，--classes 0只保留人这一类，--project和--name自定义输出目录，--exist-ok表示复用同名目录不递增。跑通标准图之后，我习惯再加一条带--save-txt的命令，确认坐标文件能正常落盘，等于把「推理 → 可视化 → 落盘」三个环节都验证了一遍。

结果去哪看：默认在runs/detect/exp下，图片上会画出框和类别标签。判断是否真跑通，别只看有没有输出文件，看三件事——终端最后一行是否打印出Results saved to runs\detect\exp、图片上框的位置是否贴着物体、标签文字是不是合理类别。框歪了或标签乱跳，多半是权重下错了版本或者输入尺寸和训练时差太多，不是环境问题。

最后提醒一个版本差异：较新版本的detect.py把--img改成了--imgsz，旧参数在多数版本里仍被兼容解析，但如果终端报unrecognized arguments: --img，直接换成--imgsz 416就行，不用怀疑环境。

从那以后我每次装完这套环境，都强制走一遍「check_env.py看 cuda 是否为 True → 一张 416 的图跑 detect → 确认 runs 目录有输出」这三步，任何一步不过就不往下走。血泪经验是跳过自检直接上训练，跑到第三个 epoch 才发现显卡压根没用上，白等一晚上。希望帮到你。

本文还有配套的精品资源，点击获取