YOLOv5目标检测环境配置：PyTorch与CUDA版本匹配及排错指南

简介《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.10nvidia-smi右上角写着 CUDA Version 12.x照着教程敲一句pip install torch torchvision装完torch.cuda.is_available()返回 Falsedetect.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 listconda --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创建虚拟环境的命令本身很短但python3.8这个数字值得单独说一下# 创建名为 yolov5_env 的虚拟环境指定 Python 3.8 conda create --name yolov5_env python3.8 -y # 激活环境后续所有安装都在这个环境里做 conda activate yolov5_env--name后面是环境名起什么都可以但建议固定成yolov5_env这样对照各种教程时不会搞混。-y表示跳过确认提示省一次回车。python3.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 -Vwhere 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. 装 PyTorchCUDA 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 挑当前索引里最新的兼容版本如果你想固定版本把包名写成torchx.y.zcu113的形式具体版本号从索引页上抄别照抄别人的博客——索引会随版本更新变化。二是网络慢导致下载中断时会留下半包重试前先pip cache purge清一下缓存否则可能一直卡在同一个坏包上。装完再补一个运行期依赖项目里 detect.py 的进度条和部分工具函数会用到# 补装常用依赖避免后续脚本 import 时报缺包 pip install numpy opencv-python pillow pyyaml tqdm matplotlib这条不是必须第 4 章装requirements.txt时会一起覆盖先手装一遍的好处是能把错误尽早暴露在这个环节而不是等到一堆依赖装完才报错。3.3 装完立刻自检六行脚本看清 torch 到底认没认到显卡装完不看一眼就用等于把问题往后拖。新建一个check_env.pyimport 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: Truecuda version显示11.3cudnn 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.yamldata/下放数据集配置 yamlutils/是工具函数。第 5 章的坑和第 6 章的验证都会回到这几个路径上。有个细节值得留意git clone默认拉的是主分支最新代码而项目文里提到的权重链接指向 v5.0 版本。两者大体兼容但如果遇到某个参数报unrecognized arguments很可能就是代码版本和教程对不上。需要固定版本时可以切标签# 查看仓库所有标签确认要用的版本号 git tag # 切到指定版本标签名从上一句输出里抄 git checkout v5.0git 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.txtpip 会认为你之前装好的 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.ptWindows 自带的 PowerShell 里通常没有 wget硬敲会报「无法将 wget 项识别为 cmdlet」。两个替代方案一是用 curlWin10 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能看到 torchpython 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 python3.8 -y conda activate yolov5_env5.2 现象装完 requirements.txttorch.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 版本没有对应的预编译 wheelpip 退回源码编译而 Windows 上通常缺 Visual C Build ToolsLinux 上缺python3-dev。解决优先换包而不是装编译器。opencv-python换opencv-python-headlessthop单独装一个明确版本。真要编译的话Windows 装 Build ToolsLinux 装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 05.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、图片上框的位置是否贴着物体、标签文字是不是合理类别。框歪了或标签乱跳多半是权重下错了版本或者输入尺寸和训练时差太多不是环境问题。参数作用常用取值调错的后果--weights指定权重文件yolov5s.pt路径错直接报文件不存在--source输入源图片/目录/视频/0路径含中文会静默失败--img推理输入尺寸416、64032 的倍数非 32 倍数报 shape 错误--conf置信度阈值0.250.5过高漏检、过低误检--iouNMS 合并阈值0.450.5过低会吞掉密集目标--device计算设备0或cpu多卡机器不指定可能抢卡最后提醒一个版本差异较新版本的detect.py把--img改成了--imgsz旧参数在多数版本里仍被兼容解析但如果终端报unrecognized arguments: --img直接换成--imgsz 416就行不用怀疑环境。从那以后我每次装完这套环境都强制走一遍「check_env.py看 cuda 是否为 True → 一张 416 的图跑 detect → 确认 runs 目录有输出」这三步任何一步不过就不往下走。血泪经验是跳过自检直接上训练跑到第三个 epoch 才发现显卡压根没用上白等一晚上。希望帮到你。本文还有配套的精品资源点击获取