简介：面向初次接触实时目标检测的开发者与工程技术人员，这套教程文档围绕 YOLOv5 的环境搭建与推理实践展开，兼顾 Windows、macOS、Linux 三类平台，并针对 GPU 加速场景说明 CUDA 10.2 与 cuDNN 7.6 以上的版本匹配要求。内容从 Anaconda 虚拟环境创建、PyTorch 与依赖库安装、官方源码克隆，到调用预训练模型完成首例图像或视频检测，逐一给出可直接执行的命令与参数说明，并解释输入尺寸、置信度阈值与非极大抑制阈值的实际作用；末尾延伸至自定义数据集的格式准备、配置文件类别修改与训练脚本调用，为定制化研究留出入口。压缩包内共 1 个 docx 文档，约 19KB，体量轻便、即下即读。已有 239 人下载学习，既可用作理论教学材料，也可作为工程项目参考，读者可借此理清完整部署思路与常见问题的排查线索。

1. 先别急着跑 detect.py：YOLOv5 环境搭建的第一道坎

第一次在本地搭 YOLOv5 目标检测环境，最容易被忽略的不是 detect.py 的参数，而是 conda 环境里 Python 3.8、PyTorch、CUDA 11.3 与 cuDNN 的版本对齐。某开发者把 CPU 版 PyTorch 装进 GPU 环境，日志里torch.cuda.is_available()一直是 False，却回头怀疑模型权重和检测脚本。

YOLOv5 环境搭建在 Windows、Linux、macOS 上都常见，装不好时的表现很统一：依赖冲突、CUDA 不可用、结果目录不生成。这套流程适合刚接触目标检测、准备跑通第一个示例的人，也适合需要重装环境、把训练前自检固定下来的工程人员。先把版本表列清，再按虚拟环境、PyTorch、依赖、权重、检测、排错的顺序走，后面每一步都尽量落成可复制的命令。

2. 环境准备：Python 3.8、CUDA 11.3 与 cuDNN 的版本对齐

YOLOv5 的安装难点不在 clone 源码，而在版本表。原文给的最低要求是 Python 3.6 以上、CUDA 10.2 以上、cuDNN 7.6 以上，示例里创建的是 Python 3.8 环境，PyTorch 安装示例提到 CUDA 11.3。最低要求只能保证“理论上能装”，实际落地时我一般先看驱动支持到哪一档，再看 PyTorch 轮子能不能对上，最后才决定装 GPU 版还是 CPU 版。

这张表里最容易误读的是 CUDA 两行。nvidia-smi右上角显示的 CUDA Version 是驱动支持上限，nvcc -V显示的是本机 CUDA Toolkit 版本，两者不一致很常见。某开发者看到nvidia-smi显示 11.4，就以为本机已经是 CUDA 11.4，结果nvcc是 10.2，PyTorch 又装了 cu113 的轮子，最后 CUDA 假可用。先把这三个信息分开看，再决定装哪个轮子。

2.1 先确认显卡驱动、CUDA Toolkit 与 cuDNN 的可见性

Linux 下我一般先跑三行，不急着创建环境。Windows 把which换成where，macOS 没有 NVIDIA CUDA 的话直接按 CPU 版走，别在nvidia-smi上耗时间。

# Linux 下先看驱动能支持到哪一档 CUDA nvidia-smi # 再看本机 CUDA Toolkit 编译器版本 nvcc -V # 确认当前 shell 用的 Python 是哪一个 python -V which python

nvidia-smi主要看驱动版本、显卡型号和右上角 CUDA Version，它不代表 Toolkit 已装好；nvcc -V才是 Toolkit 版本。python -V和which python用来确认你没有在 base 环境或系统 Python 里操作。cuDNN 在装 PyTorch 之前不一定有独立命令可查，常见做法是装完 PyTorch 后用torch.backends.cudnn.version()看它是否启用。

如果nvidia-smi能出表，但nvcc -V报找不到命令，说明驱动有、Toolkit 没进 PATH，或者根本没装 Toolkit。此时不要硬装 GPU 版 PyTorch，先把驱动和 Toolkit 对齐；只想先跑通流程的话，装 CPU 版更省事。GPU 机上torch.cuda.is_available()为 False 时，先看torch.version.cuda是不是 None，如果是 None，多半装成了 CPU 轮子，不是模型问题。

提示：驱动版本旧、Toolkit 版本新，是 CUDA 假可用的常见组合。先升级驱动，或者把 PyTorch 轮子换到与驱动匹配的 CUDA 版本，不要只改环境变量。

2.2 用 Anaconda 创建 Python 3.8 虚拟环境

原文给的是conda create --name yolov5_env python=3.8。我一般加-y省掉交互确认，创建完立刻确认解释器路径，避免后面pip install全装进 base。

# 创建名为 yolov5_env 的 Python 3.8 环境 conda create --name yolov5_env python=3.8 -y # 激活环境 conda activate yolov5_env # 确认解释器路径，避免仍在 base 环境里装包 python -V which python python -m pip -V

--name后面是环境名，python=3.8是版本约束，-y表示自动确认。which python应该指向 conda 环境目录，而不是/usr/bin/python。Windows 下用where python，输出里应该能看到yolov5_env路径。python -m pip -V比直接pip -V更稳，能确认 pip 绑在哪个解释器上。

conda activate报“命令未找到”或激活后没变化，常见原因是 shell 没初始化。bash 下跑一次conda init bash，重开终端再激活；zsh 换conda init zsh。不要在这个时候装依赖，先把环境激活状态确认清楚。虚拟环境的名字不是固定的，yolov5_env只是原文示例，换成项目名也可以，但后文命令要跟着改。

2.3 安装 PyTorch：GPU 版与 CPU 版的选择

原文给了两条安装命令：CUDA 11.3 环境用pip install torch torchvision，纯 CPU 环境用pip install torch torchvision cpuonly。这两条适合演示流程，实际落地时不要盲目复制不锁版本的命令，因为 pip 可能解析到与当前 CUDA 不匹配的轮子，也可能顺手升级 numpy。

# 原文示例：CUDA 11.3 环境 pip install torch torchvision # 原文示例：纯 CPU 环境 pip install torch torchvision cpuonly

torch是主框架，torchvision带视觉相关算子，cpuonly表示不装 CUDA 依赖。GPU 机上我更常见的做法是先用官方选择器生成带 CUDA 标记的安装命令，或者把 torch、torchvision 版本固定下来再装；CPU 机上用cpuonly能少掉一大串 CUDA 库。装完不要只看“Successfully installed”，要跑一段 Python 验证。

import torch print("torch:", torch.__version__) print("cuda available:", torch.cuda.is_available()) print("cuda runtime:", torch.version.cuda) print("cudnn:", torch.backends.cudnn.version()) # 只有 CUDA 可用时才取显卡名 if torch.cuda.is_available(): print("device:", torch.cuda.get_device_name(0))

torch.__version__看框架版本，torch.cuda.is_available()看当前轮子能不能调用 GPU，torch.version.cuda为 None 基本就是 CPU 版，torch.backends.cudnn.version()为 None 说明 cuDNN 没启用。get_device_name(0)只在 CUDA 可用时执行，避免在 CPU 机上直接报错。GPU 机装完显示cuda available: False，先重装匹配轮子，不要急着改 YOLOv5 代码。

2.4 固定依赖版本与导出环境快照

YOLOv5 的requirements.txt会装一批依赖，后面再装别的包时可能把 torch 或 numpy 顶掉。我一般在这个干净状态先导出一份快照，重装时至少有后悔药。

# 记录当前环境，重装时少走弯路 python -m pip freeze > requirements-lock.txt # 检查依赖之间是否有明显冲突 python -m pip check

pip freeze会把当前环境所有包和版本写进文件，pip check用来发现依赖声明冲突。锁文件不要跨平台硬套，Linux 和 Windows 的轮子不一样，最好分开放。常见做法是只锁关键包：torch、torchvision、numpy、opencv-python，其他依赖让requirements.txt自己解析。这个快照不是给所有人复制的，是给你自己重装时对照的。

3. 获取源码与安装依赖：YOLOv5 仓库、requirements.txt 与 yolov5s.pt

环境确认完，下一步才是拿源码。YOLOv5 的目录里有detect.py、train.py、requirements.txt、models/、data/，后面所有命令都默认在仓库根目录执行。某实验室在子目录里跑python detect.py，报找不到文件，最后发现是工作目录不对。先把目录站稳，再谈依赖和权重。

3.1 克隆 YOLOv5 仓库并确认目录结构

仓库地址用变量接一下，避免命令写死。下面尖括号里的内容要替换成 YOLOv5 官方仓库地址，不要原样复制尖括号。

# 把尖括号内容替换为 YOLOv5 官方仓库地址 REPO_URL="<YOLOv5 官方仓库地址>" git clone "$REPO_URL" yolov5 cd yolov5 # 确认关键文件在不在 ls detect.py train.py requirements.txt models data

git clone第二个参数yolov5是本地目录名，cd yolov5进入仓库根目录。ls这一行是自检：detect.py和train.py在，requirements.txt在，models/和data/在，说明源码结构完整。如果本地已经有源码，更新前先看git status，有本地修改就先备份，不要直接git pull覆盖配置。

Windows 下没有ls就用dir，或者用 Git Bash。克隆失败先看网络和地址，不要把仓库地址贴到脚本里反复重试。仓库目录名可以改，但后文命令里的cd yolov5要跟着改。进入目录后跑一次pwd，确认当前路径以yolov5结尾，后面相对路径才不会飘。

3.2 安装 requirements.txt：先 PyTorch 后依赖的顺序

依赖安装顺序我一般按“先 PyTorch，再 requirements”走。原因是requirements.txt里可能包含 torch 相关声明，先装框架再装依赖，至少能看出是谁把版本顶掉的。原文的顺序是进入目录后直接pip install -r requirements.txt，如果前面已经装好 PyTorch，这一步通常没问题。

# 先升级 pip，减少旧解析器带来的依赖回退 python -m pip install --upgrade pip # 安装 YOLOv5 依赖 pip install -r requirements.txt # 装完检查依赖冲突 python -m pip check

-r requirements.txt表示按文件里的清单安装，--upgrade pip只是升级安装器，不动业务包。安装过程中如果看到 torch 被卸载重装，先停：这说明 requirements 里的 torch 声明和你前面装的轮子不一致。常见做法是把 requirements 里的 torch 行临时注释掉，装完其他依赖后再把匹配的 torch 装回来；或者直接按锁文件装。pip check报冲突时，先看冲突包名，不要一口气全升级。

依赖装完后，导入几个关键包确认没有缺库：

import cv2 import numpy import torch import yaml print("opencv:", cv2.__version__) print("numpy:", numpy.__version__) print("torch:", torch.__version__) print("yaml ok")

cv2对应 opencv-python，numpy是数值计算，yaml读数据配置，torch是框架。任何一行报ModuleNotFoundError，就回到requirements.txt看对应包有没有装成功。Linux 精简系统上cv2可能报libGL.so.1缺失，这是系统库问题，不是 Python 包问题，后面排错章会写。

3.3 下载 yolov5s.pt 并校验文件可用性

原文用yolov5s.pt做示例，模型选择上 s 版本适合第一个检测闭环，先确认流程能跑，再换更大模型。下载地址同样用变量接，尖括号内容替换成官方发布地址。

# 把尖括号内容替换为 yolov5s.pt 官方发布地址 WEIGHTS_URL="<yolov5s.pt 官方发布地址>" # Linux / macOS wget "$WEIGHTS_URL" -O yolov5s.pt # Windows PowerShell 可以用 curl # curl -L "$WEIGHTS_URL" -o yolov5s.pt ls -lh yolov5s.pt

-O指定保存文件名，ls -lh看文件大小是否正常。权重文件下载不完整时，detect.py会在加载阶段报错，而不是在检测阶段报错。再用 Python 做一次轻量加载检查：

import torch # 只验证文件能不能被 torch 读出来，不打印完整权重 ckpt = torch.load("yolov5s.pt", map_location="cpu") print("checkpoint type:", type(ckpt))

map_location="cpu"表示先加载到 CPU，避免在没有 GPU 的机器上直接失败。这行只验证文件结构，不保证类别和模型完全匹配。如果torch.load报unpickling或文件截断，重新下载权重，不要反复改代码。权重文件放在仓库根目录时，--weights yolov5s.pt就能直接找到；放在别处就写绝对路径。

3.4 用导入自检把依赖问题挡在检测之前

检测脚本一跑，报错会混着日志和路径信息，不如先做导入自检。下面这段不依赖图片，只验证 Python 环境、torch、opencv 和 yaml 能不能协同工作。

import torch import cv2 assert torch.__version__, "torch 未正确安装" assert cv2.__version__, "opencv 未正确安装" print("torch:", torch.__version__) print("cuda:", torch.cuda.is_available()) print("opencv:", cv2.__version__) print("import check passed")

assert用来在版本信息为空时提前失败，print用来留下现场。cuda为 False 不一定是错误，CPU 机本来就该是 False；GPU 机才需要进一步查轮子。导入自检通过后再跑检测，报错范围会小很多。这一步不替代后面的端到端验证，只是把“包没装好”和“参数写错了”分开。

4. 配置检测参数：detect.py 的 --img、--conf、--iou 与结果目录

YOLOv5 的第一个检测闭环靠detect.py，参数不多，但每个都影响结果。原文示例是--weights yolov5s.pt --source test.jpg --img 416 --conf 0.4 --iou 0.5，这组参数适合先跑通，不适合所有场景。某图像处理 Demo 用 416 跑小目标，结果图上框很少，以为是模型不行，后来把--img提到 640 才看到目标。参数不是玄学，但调错方向确实很磨人。

4.1 第一次运行 detect.py：用 test.jpg 跑通最小闭环

先把一张测试图放在仓库根目录，文件名test.jpg。命令在仓库根目录执行，--source写相对路径或绝对路径都可以，但工作目录必须对。

python detect.py \ --weights yolov5s.pt \ --source test.jpg \ --img 416 \ --conf 0.4 \ --iou 0.5

--weights指定预训练模型路径，--source指定检测图像或视频路径，--img是输入图像大小，--conf是置信度阈值，--iou是非极大抑制的 IoU 阈值。第一次跑不加--device，脚本会自己选设备；GPU 机想强制 CPU 验证，可以加--device cpu。输出目录默认在runs/detect/exp，第二次跑会变成exp2，不要以为结果没生成。

如果图片不在根目录，--source写绝对路径更稳，例如--source /data/test.jpg。Windows 路径带空格时加引号。命令换行用反斜杠是 Linux/macOS 写法，Windows CMD 可以写成一行。先跑单张图，不要一上来跑视频或整个目录，单张图能最快定位路径和权重问题。

4.2 参数取舍：416 与 640、conf 与 iou 怎么调

这组参数没有万能值，只有取舍。下面这张表按常见使用场景整理，不是官方推荐表，是我自己调参时先看的几个方向。

--img 416是原文示例，跑得快，适合先确认流程；--img 640对中小目标更友好，但显存占用和推理时间会上去。--conf 0.4调低到 0.25 可能多出一批低置信框，调高到 0.6 会明显减少框。--iou 0.5影响 NMS 合并重叠框的力度，密集场景可以适当调高，普通单目标场景不用大改。--classes接类别 ID，多个 ID 用空格分隔，适合只想看某一类的情况。

调参时一次只动一个，不要同时改--img、--conf、--iou，否则结果变化了也不知道是谁的贡献。先用固定图片跑三组：416/0.4/0.5、640/0.4/0.5、640/0.25/0.5，对比框数量和误检，再决定项目用哪组。显存不够时先降--img或换更小模型，不要硬撑。

4.3 输出目录与日志：确认检测结果真的生成

跑完命令不要只看终端最后一行，去结果目录看一眼。默认输出在runs/detect/exp，里面有标注后的图片，开--save-txt还会生成标签文件。

# 看最近一次检测输出 ls -lh runs/detect/exp # 如果开了 --save-txt，标签在同级 labels 目录 ls -lh runs/detect/exp/labels # 找最近生成的图片文件 find runs/detect -maxdepth 2 -type f | head

ls看文件是否生成，find用来确认输出到底落在哪一层。--save-txt保存检测框坐标，--save-conf把置信度一起写进标签。日志里出现image 1/1和检测耗时，说明推理走过；如果日志有推理但目录空，先看--project和--name有没有被改过。输出路径带中文或空格时，优先换英文路径测试。

我一般会给每次检测起名字，避免exp、exp2分不清：

python detect.py \ --weights yolov5s.pt \ --source test.jpg \ --img 416 \ --conf 0.4 \ --iou 0.5 \ --project runs/detect \ --name test_416_conf04

--project指定父目录，--name指定本次运行目录名。这样结果目录可读，后面对比参数也方便。--name不要带斜杠，带斜杠容易被当成多级路径。输出目录不是越深越好，固定在runs/detect下最省心。

4.4 从检测到训练：data yaml、cfg 的 nc 与 train.py 参数

检测跑通后再碰训练。原文的进阶步骤是准备 YOLO 格式数据集、修改models/yolov5s.yaml中的类别数量、运行train.py。数据配置文件我一般写成下面这样，路径按自己的数据集改。

# data/mydata.yaml path: ../datasets/mydata train: images/train val: images/val nc: 3 names: ["class_a", "class_b", "class_c"]

path是数据集根目录，train和val是相对根目录的图片路径，nc是类别数，names是类别名列表。nc必须和实际标注类别数一致，names顺序要和标注 ID 对上。原文要求改models/yolov5s.yaml中的类别数量，我一般还会确认 data yaml 的nc与 cfg 里的nc一致，避免训练时类别数错位。

python train.py \ --img 416 \ --batch 16 \ --epochs 300 \ --data data/mydata.yaml \ --cfg models/yolov5s.yaml \ --weights yolov5s.pt \ --cache

--img是训练输入尺寸，--batch是批大小，--epochs是训练轮数，--data指向数据配置，--cfg指向模型结构，--weights用预训练权重做初始化，--cache把图片缓存起来加速读取。显存不够时先把--batch降到 8 或 4，再考虑降--img；--cache在内存紧张时可能帮倒忙，可以换成--cache disk或不加。训练输出在runs/train/exp，先看日志有没有正常读入图片和标签，再谈精度。

5. 避坑与排查：YOLOv5 安装后 CUDA 假可用、依赖冲突与显存不足

安装阶段的问题有规律，下面五条是重装时最常碰到的。每条按现象、原因、解决写，能对上就先处理，对不上再回头看环境表。血泪经验是：不要在一次报错里同时改 Python、CUDA、PyTorch 和依赖，变量太多，最后不知道哪一步修好的。

5.1 torch.cuda.is_available() 为 False，但显卡明明在

现象：nvidia-smi能出表，torch.cuda.is_available()返回 False，torch.version.cuda是 None 或与预期不符。

原因：装成了 CPU 版 PyTorch，或者装的是 cu113 轮子但驱动只支持到更低版本，也可能是虚拟环境没激活，验证的是另一个 Python。

解决：先确认解释器路径和 torch 版本，再决定重装哪个轮子。不要先改 YOLOv5 代码。

# 确认当前环境 which python python -V # 看 torch 是不是 CPU 版 python -c "import torch; print(torch.__version__, torch.version.cuda, torch.cuda.is_available())"

torch.version.cuda为 None 时，基本是 CPU 轮子，按 GPU 环境重装匹配版本；不为 None 但is_available()为 False，优先看驱动版本和 CUDA 运行库。重装前先pip uninstall torch torchvision，再装目标轮子，避免新旧文件混在一起。装完再跑一次验证，不要只看安装日志。

5.2 装完 requirements.txt，torch 被换掉或 CUDA 又不可用

现象：前面 PyTorch 验证通过，执行pip install -r requirements.txt后，torch.cuda.is_available()又变 False，或者 torch 版本变了。

原因：requirements.txt里包含 torch 相关声明，pip 按自己的解析结果重装或降级了 torch，覆盖了前面装好的匹配轮子。

解决：先看 requirements 里有没有 torch 行，再决定是否临时注释。

# 找 requirements 里的 torch 相关行 grep -n -i "torch" requirements.txt # 如果确认是它覆盖，先备份再临时注释 torch 行 cp requirements.txt requirements.txt.bak # 编辑 requirements.txt，把 torch / torchvision 行前面加 # pip install -r requirements.txt # 最后把匹配的 torch 装回来 pip install torch torchvision

grep -n带行号，方便定位；cp是备份，改坏了能恢复。注释 torch 行不是长久方案，只是把安装顺序拆开。装完其他依赖后，再按环境表装回匹配的 torch。pip check如果报 numpy 或 opencv 冲突，按冲突包单独处理，不要一口气全升级。

5.3 Linux 下导入 cv2 报 libGL.so.1 缺失

现象：python -c "import cv2"报ImportError: libGL.so.1: cannot open shared object file，但 pip 显示 opencv-python 已安装。

原因：精简版 Linux 缺少 OpenCV 依赖的图形系统库，Python 包本身装上了，系统库没装上。

解决：按系统包管理器补库，不要反复重装 opencv-python。

# Debian / Ubuntu 系常见补法 sudo apt-get update sudo apt-get install -y libgl1 # 再验证导入 python -c "import cv2; print(cv2.__version__)"

libgl1提供libGL.so.1，apt-get update先刷新索引。不同发行版包名不一样，找不到就查对应系统的 OpenCV 依赖包。装完系统库后不需要重装 Python 包，直接再导入一次。服务器上没有图形界面时，这个报错很常见，不要误判成 opencv 版本不对。

5.4 CUDA out of memory：显存不足不一定是模型太大

现象：检测或训练跑到一半报CUDA out of memory，有时换一张小图又能跑。

原因：--img或--batch太大，--cache占内存，后台还有其他进程占显存，或者模型本身超出了当前显卡容量。

解决：先降输入尺寸和批大小，再用 CPU 跑一次确认不是代码问题。

# 检测阶段先降尺寸 python detect.py --weights yolov5s.pt --source test.jpg --img 320 --conf 0.4 --iou 0.5 # 训练阶段先降 batch python train.py --img 416 --batch 8 --epochs 10 --data data/mydata.yaml --cfg models/yolov5s.yaml --weights yolov5s.pt

--img 320和--batch 8是排错起点，不是最终参数。先用小批量确认能跑，再逐步往上加。--cache在内存紧张时去掉，或者改成--cache disk。还要看有没有别的 Python 进程占着显存，必要时关掉再跑。显存不足时不要只改--workers，它主要影响数据加载，不解决模型和输入占显存的问题。

5.5 检测日志有输出，但结果目录找不到图片

现象：终端显示推理完成，runs/detect/exp里没有图片，或者图片生成在别的目录。

原因：工作目录不在 YOLOv5 根目录，--source用了相对路径，--project/--name被改过，或者结果目录被同名文件占用。

解决：先确认当前路径，再用绝对路径和固定输出名跑一次。

# 确认在仓库根目录 pwd ls detect.py # 用绝对路径指定图片，并固定输出目录 python detect.py \ --weights yolov5s.pt \ --source /absolute/path/test.jpg \ --img 416 \ --conf 0.4 \ --iou 0.5 \ --project runs/detect \ --name check_001 # 去固定目录看结果 ls -lh runs/detect/check_001

pwd和ls detect.py确认工作目录，/absolute/path/test.jpg换成实际图片路径，--project和--name把输出钉在可预期位置。Windows 路径用反斜杠时加引号，或者统一用正斜杠。结果目录找不到时，先在终端日志里搜Results saved to，以日志打印的路径为准，不要凭记忆找。

6. 装完怎么验证：三行自检、一次检测与结果目录核对

装完环境后，我一般不看安装日志，直接跑三行自检。第一行确认 torch 能导入，第二行确认 CUDA 状态，第三行确认 opencv 能用。这三行过了，再跑一张固定图片，最后核对结果目录和日志。验证不是走形式，是把“装完了”变成“能复现”。

6.1 三行自检脚本

import torch import cv2 print("torch:", torch.__version__) print("cuda available:", torch.cuda.is_available()) print("cuda runtime:", torch.version.cuda) print("opencv:", cv2.__version__)

torch.__version__和cv2.__version__用来确认包真的进了当前环境，cuda available和

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