简介面向初次接触实时目标检测的开发者与工程技术人员这套教程文档围绕 YOLOv5 的环境搭建与推理实践展开兼顾 Windows、macOS、Linux 三类平台并针对 GPU 加速场景说明 CUDA 10.2 与 cuDNN 7.6 以上的版本匹配要求。内容从 Anaconda 虚拟环境创建、PyTorch 与依赖库安装、官方源码克隆到调用预训练模型完成首例图像或视频检测逐一给出可直接执行的命令与参数说明并解释输入尺寸、置信度阈值与非极大抑制阈值的实际作用末尾延伸至自定义数据集的格式准备、配置文件类别修改与训练脚本调用为定制化研究留出入口。压缩包内共 1 个 docx 文档约 19KB体量轻便、即下即读。已有 239 人下载学习既可用作理论教学材料也可作为工程项目参考读者可借此理清完整部署思路与常见问题的排查线索。1. 先别急着跑 detect.pyYOLOv5 环境搭建的第一道坎第一次在本地搭 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 版。组件最低要求示例取值检查方式备注操作系统Windows / macOS / LinuxLinuxuname -a命令写法按 shell 调整Python3.6 以上3.8python -V必须在虚拟环境内确认CUDA10.2 以上GPU 才需要11.3nvcc -V驱动支持上限看nvidia-smicuDNN7.6 以上GPU 才需要与 CUDA 匹配装完 PyTorch 后查版本不是单独命令能看全PyTorch与 CUDA / CPU 选择匹配按官方轮子安装torch.__version__不要盲装不锁版本的包这张表里最容易误读的是 CUDA 两行。nvidia-smi右上角显示的 CUDA Version 是驱动支持上限nvcc -V显示的是本机 CUDA Toolkit 版本两者不一致很常见。某开发者看到nvidia-smi显示 11.4就以为本机已经是 CUDA 11.4结果nvcc是 10.2PyTorch 又装了 cu113 的轮子最后 CUDA 假可用。先把这三个信息分开看再决定装哪个轮子。2.1 先确认显卡驱动、CUDA Toolkit 与 cuDNN 的可见性Linux 下我一般先跑三行不急着创建环境。Windows 把which换成wheremacOS 没有 NVIDIA CUDA 的话直接按 CPU 版走别在nvidia-smi上耗时间。# Linux 下先看驱动能支持到哪一档 CUDA nvidia-smi # 再看本机 CUDA Toolkit 编译器版本 nvcc -V # 确认当前 shell 用的 Python 是哪一个 python -V which pythonnvidia-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 python3.8。我一般加-y省掉交互确认创建完立刻确认解释器路径避免后面pip install全装进 base。# 创建名为 yolov5_env 的 Python 3.8 环境 conda create --name yolov5_env python3.8 -y # 激活环境 conda activate yolov5_env # 确认解释器路径避免仍在 base 环境里装包 python -V which python python -m pip -V--name后面是环境名python3.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 安装 PyTorchGPU 版与 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 cpuonlytorch是主框架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()看当前轮子能不能调用 GPUtorch.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 checkpip 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_URLYOLOv5 官方仓库地址 git clone $REPO_URL yolov5 cd yolov5 # 确认关键文件在不在 ls detect.py train.py requirements.txt models datagit 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-pythonnumpy是数值计算yaml读数据配置torch是框架。任何一行报ModuleNotFoundError就回到requirements.txt看对应包有没有装成功。Linux 精简系统上cv2可能报libGL.so.1缺失这是系统库问题不是 Python 包问题后面排错章会写。3.3 下载 yolov5s.pt 并校验文件可用性原文用yolov5s.pt做示例模型选择上 s 版本适合第一个检测闭环先确认流程能跑再换更大模型。下载地址同样用变量接尖括号内容替换成官方发布地址。# 把尖括号内容替换为 yolov5s.pt 官方发布地址 WEIGHTS_URLyolov5s.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_locationcpu) print(checkpoint type:, type(ckpt))map_locationcpu表示先加载到 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 机本来就该是 FalseGPU 机才需要进一步查轮子。导入自检通过后再跑检测报错范围会小很多。这一步不替代后面的端到端验证只是把“包没装好”和“参数写错了”分开。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 / 640小目标更容易看到显存和耗时上升速度更快小目标容易丢--conf置信度阈值0.4误检少漏检多框更多误检也会多--iouNMS 的 IoU 阈值0.5重叠框保留更多重叠框抑制更激进--max-det单图最大检测数默认值保留更多框限制输出数量--classes只保留指定类别按类别 ID不适用不适用--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 | headls看文件是否生成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()返回 Falsetorch.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.txttorch 被换掉或 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 torchvisiongrep -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.1apt-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_001pwd和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和本文还有配套的精品资源点击获取 简介面向初次接触实时目标检测的开发者与工程技术人员这套教程文档围绕 YOLOv5 的环境搭建与推理实践展开兼顾 Windows、macOS、Linux 三类平台并针对 GPU 加速场景说明 CUDA 10.2 与 cuDNN 7.6 以上的版本匹配要求。内容从 Anaconda 虚拟环境创建、PyTorch 与依赖库安装、官方源码克隆到调用预训练模型完成首例图像或视频检测逐一给出可直接执行的命令与参数说明并解释输入尺寸、置信度阈值与非极大抑制阈值的实际作用末尾延伸至自定义数据集的格式准备、配置文件类别修改与训练脚本调用为定制化研究留出入口。压缩包内共 1 个 docx 文档约 19KB体量轻便、即下即读。已有 239 人下载学习既可用作理论教学材料也可作为工程项目参考读者可借此理清完整部署思路与常见问题的排查线索。1. 先别急着跑 detect.pyYOLOv5 环境搭建的第一道坎第一次在本地搭 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 版。组件最低要求示例取值检查方式备注操作系统Windows / macOS / LinuxLinuxuname -a命令写法按 shell 调整Python3.6 以上3.8python -V必须在虚拟环境内确认CUDA10.2 以上GPU 才需要11.3nvcc -V驱动支持上限看nvidia-smicuDNN7.6 以上GPU 才需要与 CUDA 匹配装完 PyTorch 后查版本不是单独命令能看全PyTorch与 CUDA / CPU 选择匹配按官方轮子安装torch.__version__不要盲装不锁版本的包这张表里最容易误读的是 CUDA 两行。nvidia-smi右上角显示的 CUDA Version 是驱动支持上限nvcc -V显示的是本机 CUDA Toolkit 版本两者不一致很常见。某开发者看到nvidia-smi显示 11.4就以为本机已经是 CUDA 11.4结果nvcc是 10.2PyTorch 又装了 cu113 的轮子最后 CUDA 假可用。先把这三个信息分开看再决定装哪个轮子。2.1 先确认显卡驱动、CUDA Toolkit 与 cuDNN 的可见性Linux 下我一般先跑三行不急着创建环境。Windows 把which换成wheremacOS 没有 NVIDIA CUDA 的话直接按 CPU 版走别在nvidia-smi上耗时间。# Linux 下先看驱动能支持到哪一档 CUDA nvidia-smi # 再看本机 CUDA Toolkit 编译器版本 nvcc -V # 确认当前 shell 用的 Python 是哪一个 python -V which pythonnvidia-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 python3.8。我一般加-y省掉交互确认创建完立刻确认解释器路径避免后面pip install全装进 base。# 创建名为 yolov5_env 的 Python 3.8 环境 conda create --name yolov5_env python3.8 -y # 激活环境 conda activate yolov5_env # 确认解释器路径避免仍在 base 环境里装包 python -V which python python -m pip -V--name后面是环境名python3.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 安装 PyTorchGPU 版与 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 cpuonlytorch是主框架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()看当前轮子能不能调用 GPUtorch.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 checkpip 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_URLYOLOv5 官方仓库地址 git clone $REPO_URL yolov5 cd yolov5 # 确认关键文件在不在 ls detect.py train.py requirements.txt models datagit 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-pythonnumpy是数值计算yaml读数据配置torch是框架。任何一行报ModuleNotFoundError就回到requirements.txt看对应包有没有装成功。Linux 精简系统上cv2可能报libGL.so.1缺失这是系统库问题不是 Python 包问题后面排错章会写。3.3 下载 yolov5s.pt 并校验文件可用性原文用yolov5s.pt做示例模型选择上 s 版本适合第一个检测闭环先确认流程能跑再换更大模型。下载地址同样用变量接尖括号内容替换成官方发布地址。# 把尖括号内容替换为 yolov5s.pt 官方发布地址 WEIGHTS_URLyolov5s.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_locationcpu) print(checkpoint type:, type(ckpt))map_locationcpu表示先加载到 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 机本来就该是 FalseGPU 机才需要进一步查轮子。导入自检通过后再跑检测报错范围会小很多。这一步不替代后面的端到端验证只是把“包没装好”和“参数写错了”分开。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 / 640小目标更容易看到显存和耗时上升速度更快小目标容易丢--conf置信度阈值0.4误检少漏检多框更多误检也会多--iouNMS 的 IoU 阈值0.5重叠框保留更多重叠框抑制更激进--max-det单图最大检测数默认值保留更多框限制输出数量--classes只保留指定类别按类别 ID不适用不适用--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 | headls看文件是否生成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()返回 Falsetorch.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.txttorch 被换掉或 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 torchvisiongrep -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.1apt-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_001pwd和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和本文还有配套的精品资源点击获取