简介这份文档面向具备一定 Python 与计算机视觉基础的入门级研究人员和工程技术人员系统讲解 YOLOv5 目标检测框架的本地环境搭建与基本使用流程。内容从系统要求入手明确 Windows、macOS 或 Linux 平台及 Python 3.6 以上版本的前提并针对 GPU 加速场景说明 CUDA 10.2 与 cuDNN 7.6 以上的版本匹配要求随后依次覆盖依赖库安装、官方源码获取、预训练模型下载与示例检测运行最后简要引介基于自定义数据集的模型训练与参数调整思路兼顾理论教学与工程实践参考。资源包共 1 个 docx 文件约 19KB以图文步骤形式组织便于按章节对照操作。目前已有 238 人学习适合初次接触 YOLOv5、希望快速跑通检测流程并理解环境配置要点的读者也可作为课程材料或项目搭建时的排错参考。1. 装 YOLOv5 前先想清楚为什么 Python 3.8 是甜点版本上周帮一位同事收拾一台被折腾了三天的机器症状很典型pip install -r requirements.txt跑到一半报torch版本冲突降级之后numpy又炸最后连python detect.py都进不去。翻了下他的环境Python 3.11 加最新版 PyTorch再混着装了个老版本 torchvision。这不是 YOLOv5 难装是版本组合没选对。YOLOv5 这套目标检测环境说常见是真常见从课程设计到产线质检的 Demo 都在用说容易翻车也是真容易翻车PyTorch、CUDA、cuDNN、torchvision 四者版本必须咬合错一个就报一堆看不懂的错。这篇笔记按我实际部署的顺序走一遍先定版本再建隔离环境装 PyTorch 和依赖跑通示例检测最后把训练入口和排错手段交代清楚。适合刚接触目标检测、准备在本地把 YOLOv5 跑起来的开发者也适合已经装过一遍但被版本问题卡住、想找一份可复现参数的人。2. 环境与版本选型Python、PyTorch、CUDA 三者的咬合关系2.1 先确认硬件和驱动再决定装 CPU 版还是 GPU 版装之前先跑一条命令看显卡状态这一步能省掉后面一半的玄学问题nvidia-smi输出里重点看两处右上角的CUDA Version是驱动支持的最高 CUDA 运行时版本不是你已经装的版本下方Driver Version决定你能装多新的 PyTorch。常见做法是驱动版本不低于 470对应 CUDA 11.x 系列比较稳。如果这条命令直接报command not found要么没装驱动要么是纯 CPU 机器那就老老实实走 CPU 路线别硬上 GPU 版 PyTorch装了也调不起来。CPU 和 GPU 两条路线的取舍很直接只是跑几张图看看效果、验证环境通不通CPU 版足够装起来还少一层 CUDA 依赖要做批量检测或者后面训练自定义数据集GPU 版是刚需train.py在 CPU 上跑 300 个 epoch 基本等于劝退。我一般会先按 CPU 版把整条链路跑通确认代码和数据没问题再换 GPU 版重装一次 PyTorch这样出问题时能快速判断是环境问题还是数据问题。2.2 版本对照表照着这张表选少走两天弯路YOLOv5 官方仓库对版本比较宽容但 PyTorch 生态内部对版本很敏感。下面这张表是我在几台机器上验证过的组合按 Python 3.8 为基准组件推荐版本说明操作系统Windows 10/11、macOS、LinuxLinux 下编译依赖最省心Python3.83.6 能跑但部分依赖已不兼容3.10 以上容易踩 wheel 缺失PyTorch1.10 ~ 1.13与 CUDA 11.3 配套成熟torchvision与 PyTorch 同批次必须成对安装不能单独升级CUDA11.3GPU 路线驱动需支持到该版本cuDNN8.xGPU 路线随 CUDA 一起装版本要匹配numpy 2.02.x 会触发部分旧接口报错Python 3.8 是这套组合里的甜点版本原因不复杂YOLOv5 的requirements.txt里不少包在 3.8 上有现成 wheel装的时候不用现场编译而 3.10 之后有些包要么没轮子、要么编译工具链对不上Windows 上尤其明显。原文写的最低要求是 Python 3.6能跑但我不建议3.6 已经停止维护很多依赖的新版本直接不支持。提示不要用系统自带的 Python 直接装。macOS 和部分 Linux 发行版自带 Python 被系统工具依赖往上装包容易把系统工具搞坏隔离环境是底线。2.3 用 conda 建隔离环境把 Python 版本钉死Anaconda 或 Miniconda 都行Miniconda 体积小、干净我一般选它。装完之后建环境# 创建名为 yolov5_env 的环境Python 版本钉在 3.8 conda create --name yolov5_env python3.8 -y # 激活环境后续所有命令都在这个环境里执行 conda activate yolov5_env # 确认当前解释器路径指向 conda 环境而不是系统 Python which python # Windows 下用 where python三条命令的逻辑第一条把 Python 版本固定下来避免后面pip装包时按系统 Python 的版本去解析依赖第二条激活环境命令行前缀会出现(yolov5_env)看到这个前缀才说明生效第三条是自检输出路径里应该包含envs/yolov5_env如果还是/usr/bin/python之类说明激活没成功后面装什么都白搭。这一步最常见的翻车是激活了环境但pip仍指向全局。判断方法很简单pip -V看输出路径是否和which python在同一目录下。不一致就先用python -m pip代替裸pip能强制走当前解释器对应的 pip。3. 安装 PyTorch 与 YOLOv5 依赖命令怎么选、参数怎么改3.1 装 PyTorchCPU 版和 GPU 版是两条命令PyTorch 的安装命令必须和硬件路线对应装错了不会立刻报错而是在torch.cuda.is_available()返回False时才暴露。CPU 路线# CPU 版本不依赖 CUDA pip install torch torchvisionGPU 路线对应 CUDA 11.3# 指定 CUDA 11.3 的 wheel 源版本号写死避免解析到最新版 pip install torch1.12.1cu113 torchvision0.13.1cu113 -f https://download.pytorch.org/whl/torch_stable.html参数说明torch1.12.1cu113里的cu113表示这个 wheel 是针对 CUDA 11.3 编译的不带这个后缀的包是 CPU 版-f指定额外的包索引地址让 pip 去官方 wheel 列表里找对应版本。为什么不直接pip install torch因为默认源解析到的是最新版可能对应 CUDA 11.8 甚至 12.x和你机器上的驱动对不上装完torch.cuda.is_available()就是False。装完立刻验证别等跑检测时才发现python -c import torch; print(torch.__version__); print(torch.cuda.is_available())输出第一行是版本号第二行 GPU 路线应该是True。如果是False先别怀疑代码按顺序查驱动版本是否支持该 CUDA、装的是不是cu后缀的包、conda 环境是否激活。这三项排完基本能定位。3.2 拉取仓库并安装依赖requirements.txt 不是无脑装拿到源码git clone https://github.com/ultralytics/yolov5.git cd yolov5进目录后先别急着pip install -r requirements.txt看一眼文件内容确认里面有没有会覆盖你刚装好的 PyTorch 的条目。YOLOv5 的依赖清单里通常包含torch、torchvision的版本约束如果它写的版本和你装的不一致pip 会尝试重装把 CUDA 版换成 CPU 版这是很隐蔽的坑。稳妥做法是先装依赖再补 PyTorch或者装依赖时加参数跳过已满足的包# 安装依赖已满足的包不重复安装 pip install -r requirements.txt如果发现 PyTorch 被降级或换成了 CPU 版回到 3.1 重装一次 GPU 版即可依赖本身不会因此损坏。依赖里还有opencv-python、matplotlib、pandas、pyyaml这些都是检测和可视化要用的装完可以用pip list扫一眼关键包是否齐全。3.3 预训练权重下载位置和校验方式示例检测需要权重文件。原文给的wget命令在 Linux 和 macOS 上可用Windows 的 CMD 里没有wget用浏览器下载或者 PowerShell 的Invoke-WebRequest都行。权重放到仓库根目录文件名保持yolov5s.pt不变脚本按这个名字找。# Linux / macOS 下载 yolov5s 权重到当前目录 wget https://github.com/ultralytics/yolov5/releases/download/v5.0/yolov5s.pt下载完确认文件大小在十几 MB 量级太小说明下到的是错误页面而不是权重。这一步看着琐碎但权重文件损坏导致的报错往往很隐晦比如加载时提示unpickling相关错误实际原因就是文件不完整。4. 跑通第一次检测detect.py 的参数逐个拆开讲4.1 最小可用命令与每个参数的含义环境齐了先用一张图验证整条链路# 对单张图片做检测输入尺寸 416置信度阈值 0.4NMS 阈值 0.5 python detect.py --weights yolov5s.pt --source test.jpg --img 416 --conf 0.4 --iou 0.5逐个说--weights指定权重路径换成自己训练的模型时改这里--source可以是单张图、整个目录、视频文件甚至填0调用摄像头--img是推理时的输入分辨率416 比默认的 640 快小目标多的话调回 640--conf是置信度阈值低于这个值的框直接丢弃调高检测更保守、误检少调低召回多、误检也多--iou是 NMS 的重叠阈值两个框重叠超过这个比例就合并密集场景可以适当调高。第一次跑建议就用这组参数别一上来就改。跑通之后再拿同一张图调--conf从 0.25 到 0.6 各跑一次观察框的数量变化对这两个阈值的手感就有了。这比看十篇参数说明都管用。4.2 结果目录与输出解读检测完成后结果落在runs/detect/exp下第二次运行会生成exp2、exp3依次递增不会覆盖。目录里除了标注好的图片还有检测结果的文本文件每行格式是类别 置信度 x_center y_center width height坐标是归一化后的值。后面做统计或者接下游业务读这个文本比解析图片方便。如果目录里没有输出先看终端有没有报错再看--source路径是否写对。相对路径是相对于执行命令时所在的目录不是相对于脚本位置这一点在从别的目录调用脚本时特别容易错。4.3 训练自定义数据集的入口参数示例跑通之后训练入口的参数结构基本一致只是多了数据配置# 训练自定义数据集输入 416批大小 16300 轮启用缓存加速 python train.py --img 416 --batch 16 --epochs 300 --data data/custom.yaml --cfg models/yolov5s.yaml --weights yolov5s.pt --cache--data指向数据配置文件里面写训练集、验证集路径和类别数、类别名--cfg是模型结构配置改类别数时要同步改这里--weights用预训练权重做初始化比从零训练收敛快得多--cache把图片缓存到内存数据集不大时能明显提速但内存吃紧的机器别开。--batch要根据显存调显存不够就往下压到 8 甚至 4报CUDA out of memory时第一个动的就是它。5. 避坑与排查五条踩过的坑按现象对号入座5.1 现象torch.cuda.is_available()返回 False原因通常是三选一装的是 CPU 版 PyTorch、驱动版本低于 CUDA 运行时要求、conda 环境没激活导致查的是另一个解释器。解决顺序是先pip list | grep torch看版本号有没有cu后缀没有就按 3.1 的 GPU 命令重装有后缀再跑nvidia-smi看驱动驱动太老就升级驱动最后确认命令行前缀有环境名。三步走完基本能解决别一上来就重装系统。5.2 现象装依赖时 PyTorch 被自动降级或替换原因在requirements.txt里的版本约束和已装版本冲突pip 为了满足约束会重装。解决方法是先装依赖、再装对应版本的 PyTorch顺序反过来或者装依赖时留意输出里有没有Uninstalling torch字样看到就中断改用pip install -r requirements.txt --no-deps只装依赖本身再手动补 PyTorch。后者更可控但需要自己确认依赖是否齐全。5.3 现象numpy相关报错提示接口不存在或类型错误原因是 numpy 2.x 改了部分接口而 YOLOv5 依赖链里有些包还按 1.x 的写法调用。解决很直接# 把 numpy 钉回 1.x 系列 pip install numpy2.0装完重启 Python 进程再跑别在同一个交互式会话里继续模块已经加载进内存了不重启不生效。5.4 现象Windows 上装依赖卡在编译报缺少 C 构建工具原因是某些包没有提供对应 Python 版本的预编译 wheelpip 退回到源码编译而机器上没有 Visual C Build Tools。解决办法优先换 Python 版本到 3.8 重新建环境多数包在 3.8 上有现成 wheel实在要编译就装 Build Tools但更省事的做法是找该包的预编译版本手动装。这也是我坚持 Python 3.8 的原因之一。5.5 现象检测结果框位置偏移或数量异常先排除参数问题--img改过之后小目标检测效果变化明显416 对密集小目标不友好调回 640 再看--conf和--iou调得过激也会让框变少或重叠框变多。参数都正常还偏检查输入图片是否被预处理过比如已经缩放或裁剪YOLOv5 内部会做 letterbox 填充外部再处理一次就会错位。这类问题没有报错只能靠对比原图和输出图定位。6. 装完怎么验证跑通三层自检和一条固定习惯环境装完不等于跑通我一般按三层自检走一遍每层都有明确的通过标准任何一层不过就停在那里排查不往下走。第一层是解释器层确认环境和包版本# 一次性打印关键版本存档备查 python -c import sys, torch, torchvision, numpy; print(sys.version); print(torch.__version__, torchvision.__version__, numpy.__version__); print(cuda:, torch.cuda.is_available())通过标准Python 是 3.8.xtorch 和 torchvision 版本成对numpy 低于 2.0GPU 路线下 cuda 为 True。这行输出建议复制存到笔记里以后环境出问题时有对照基准。第二层是推理层用官方示例图跑一次检测确认从加载权重到输出结果的链路完整。通过标准是runs/detect/exp下生成标注图终端没有警告刷屏。如果这一步过了但结果图是空的回到 5.5 查参数。第三层是训练入口层不一定要真跑完 300 轮用--epochs 1加小批量跑一轮就够# 单轮冒烟测试验证数据配置和训练链路 python train.py --img 416 --batch 4 --epochs 1 --data data/custom.yaml --cfg models/yolov5s.yaml --weights yolov5s.pt通过标准是能正常进入第一个 epoch 并输出损失值哪怕损失很大也没关系这一步验证的是数据加载、模型构建、反向传播三条链路都通。很多数据格式问题在这一步就会暴露比跑完三百轮才发现强得多。三层都过之后把这几条命令整理成一个check_env.sh或批处理文件换机器时直接跑。我现在的习惯是每装完一套深度学习环境第一件事就是把版本输出和三层自检命令写进一个文件跟项目代码放一起。之前吃过一次亏隔了两个月回来复现实验完全想不起当时装的哪个版本重装一遍又踩了同样的坑。从那以后我每次装环境都强制走一遍这三层自检并留档省下的时间远比写这几行命令多。希望帮到你。本文还有配套的精品资源点击获取