做目标检测这行的人几乎绕不开两个东西一个是训练框架另一个就是标注工具。YOLOv5 作为落地项目里出场率极高的检测框架它的数据入口标准其实非常明确——每张图对应一个同名的 txt 标签文件里面按类别 归一化中心x 归一化中心y 归一化宽 归一化高的格式逐行写目标框。而 LabelImg 就是把这个格式喂给 YOLOv5 之前最常用的一道手工工序。很多人第一次跑 YOLOv5 的train.py报错十有八九不是模型问题而是标签格式没对上要么是 VOC 的 xml 没转要么是坐标没归一化要么是类别名和data.yaml里的顺序错位。这篇内容就把 LabelImg 标注到 YOLOv5 可用标签这条链路完整拆开从工具选型、目录组织、标注规范、格式转换、批量校验到踩坑排查全部按实操顺序讲清楚。不管你是刚接触目标检测的学生还是要把一个自采数据集跑通的中小团队开发者都能照着这套流程直接复现少走几天弯路。1. 整体方案设计与工具选型思路1.1 为什么是 LabelImg 而不是别的标注工具标注工具这几年冒出来很多有在线的、有团队协作的、有带半自动预标注的。但落到 YOLOv5 这个具体场景LabelImg 依然是性价比最高的起点原因很实在。第一是输出格式直接对口。LabelImg 原生支持 Pascal VOC 的 xml 和 YOLO 的 txt 两种保存格式切到 YOLO 模式后画完框保存出来的就是归一化坐标的 txt和 YOLOv5 的标签规范完全一致中间不需要写转换脚本。这一点对新手极其友好省掉了最容易出错的一环。第二是轻量、离线、无依赖。它就是个 Python 写的桌面小工具装完就能用不联网也能标图片不出本地对数据隐私敏感的场景很合适。相比之下很多在线标注平台要把图传上去团队协作是方便了但数据流转的顾虑也多。第三是快捷键体系成熟。标数据集是个体力活一个几千张图的项目标注速度直接决定项目周期。LabelImg 的W画框、D下一张、A上一张、CtrlS保存这套组合熟练之后单手就能操作效率比很多花哨工具还高。当然它也有明显短板不支持多人协作、没有预标注、界面比较朴素。所以我的实际做法是——小数据集和冷启动阶段用 LabelImg 手工标等积累了几百张之后用训好的模型做预标注再人工修正这个混合策略后面会展开讲。1.2 YOLOv5 对标签的真实要求到底是什么很多人对 YOLO 标签格式的理解停留在五个数但真正决定你能不能跑通的是这几个细节。YOLOv5 的标签文件是每张图一个 txt文件名与图片同名扩展名不同放在与图片平行的labels目录下。txt 里每一行代表一个目标框格式为class_index x_center y_center width height其中后四个值全部是相对于图片宽高的归一化值范围 0 到 1保留六位小数左右即可。class_index是从 0 开始的类别索引必须和data.yaml里names列表的顺序严格对应。这里有个特别容易被忽略的点归一化的分母是当前这张图的实际宽高不是数据集的统一尺寸。也就是说如果你的图片尺寸参差不齐每张图的归一化基准都不一样LabelImg 在 YOLO 模式下会自动按当前图尺寸算这一点它处理得是对的。但如果你自己写脚本转换 VOC 到 YOLO就必须读每张图真实的width和height不能拿一个固定值去套否则框会整体偏移——这是新手转换脚本里最高频的 bug。还有一个隐性要求空标签的处理。如果一张图里没有目标负样本YOLOv5 期望存在一个空的 txt 文件而不是没有文件。有图无标签文件训练时会被当成标签缺失跳过或报错有空文件才被正确识别为负样本。LabelImg 在 YOLO 模式下如果一张图没画任何框就保存默认不会生成文件这个坑后面会讲怎么补。1.3 目录结构怎么组织才不返工标注阶段最忌讳的就是目录乱。我见过太多项目标到一半发现图片和标签对不上号回头整理花的时间比标注还多。推荐从一开始就按 YOLOv5 官方认可的结构来dataset/ ├── images/ │ ├── train/ │ └── val/ ├── labels/ │ ├── train/ │ └── val/ └── data.yaml关键原则是images 和 labels 两棵树的子目录名必须完全一致都叫 train、都叫 valYOLOv5 在训练时会自动把images/train/xxx.jpg映射到labels/train/xxx.txt。你只要保证这个平行关系路径配置就几乎不会出错。标注阶段的临时文件我习惯单独放一个raw/目录标完再按比例切分到 train 和 val。切分比例一般 8:2 或 9:1小数据集可以 7:3 保证验证集有足够样本。切分时要注意按图片切标签跟着图片走绝不能把同一张图的图和标签分到不同集合。提示目录名、文件名里尽量不要出现中文和空格。YOLOv5 底层读路径时对特殊字符的处理不够健壮中文路径在部分环境下会直接读不到文件这个坑非常隐蔽排查起来很费时间。2. LabelImg 环境搭建与核心配置细节2.1 安装方式的选择与取舍LabelImg 的安装有三条常见路线各有适用场景我按推荐度排一下。路线一pip 安装最省事。直接pip install labelimg装完命令行敲labelimg就能启动。适合绝大多数人尤其是 Windows 和 macOS 用户。缺点是某些系统上 Qt 依赖可能冲突如果启动报 Qt 相关错误就换路线二。路线二源码运行最可控。从仓库拉源码装好pyqt5和lxml依赖后python labelImg.py启动。适合需要改源码、加自定义功能的人比如你想改默认保存格式或者加个自动编号逻辑。路线三打包好的可执行文件最无脑。直接下载对应系统的可执行版本双击运行。适合完全不想碰 Python 环境的用户但版本可能偏旧。我个人的习惯是用 pip 装但固定一个已知稳定的版本。因为 LabelImg 更新不算频繁新版本偶尔会引入小问题固定版本能保证团队里每个人环境一致避免我这能存你那不能存的扯皮。# 推荐的基础安装 pip install labelimg # 如果遇到 Qt 报错先卸载再装指定版本 pip uninstall pyqt5 pyqt5-tools pip install pyqt55.15.92.2 启动后必须改的几个默认设置LabelImg 装完直接开标大概率会踩格式坑。启动后第一件事是进设置把几个关键项调对这几步花两分钟能省后面几小时。第一切换保存格式为 YOLO。界面左侧工具栏有个格式切换按钮默认是 PascalVOC点一下切到 YOLO。切换后保存出来的就是 txt 而不是 xml。这个一定要在开始标注之前切标到一半再切会导致前面存的格式和后面不一致混在一起非常麻烦。第二设置自动保存。菜单里勾选Auto Save mode这样每次切到下一张图时自动保存当前标注不用手动CtrlS。标几千张图的时候忘记保存丢掉的标注能让人崩溃这个开关强烈建议打开。第三配置预定义类别。在设置里找到Predefined Classes把你要标的类别一行一个写进去。这样画框时可以直接从下拉列表选类别不用每次手打既快又避免拼写不一致。类别名要和后面data.yaml里的names完全一致大小写都不能差。第四确认标注框颜色和显示。这个纯属体验优化但类别多的时候给不同类别配不同颜色能显著降低标错的概率尤其是相似类别比如货车和客车挨着出现时。2.3 快捷键体系与效率提升标注效率的核心就是少动鼠标。LabelImg 的快捷键我整理成一张表建议打印出来贴屏幕边上练熟之后速度能翻倍。操作快捷键说明画矩形框W最常用按下后拖拽画框下一张D标完一张立刻切下一张上一张A标错了回头改保存CtrlS开了自动保存可省略删除当前框Delete选中框后删除放大/缩小Ctrl滚轮小目标必用移动图片按住滚轮拖放大后平移查看复制上一张的框CtrlD连续相似场景提速神器其中CtrlD复制上一张标注框这个功能很多人不知道。在视频抽帧或者连续拍摄的场景里相邻帧的目标位置几乎一样复制过来微调比重新画快得多。我标过一个连续拍摄的数据集靠这个功能效率提升了差不多三倍。注意CtrlD复制的是上一张图的框如果两张图尺寸不同框的位置会有偏差复制后一定要检查微调不能无脑复制。3. 标注规范与实操全流程3.1 标注前的规范制定动手标之前先花半小时把规范定下来比标到一半再统一强一百倍。规范要明确三件事标什么、怎么标边界、类别怎么定义。标什么明确哪些目标要标、哪些忽略。比如做车辆检测远处的、被遮挡超过 70% 的、模糊到人眼都难辨的是标还是不标这些边界情况必须提前定规则。我的习惯是——遮挡超过 70% 或尺寸小于 10x10 像素的目标不标因为这类目标即使标了模型也学不好反而引入噪声。怎么标边界框要贴紧目标的外接矩形不能松也不能切。松了会把背景算进目标切了会丢失目标信息。对于有遮挡的目标框按可见部分的完整外接矩形来画被遮挡的部分靠推理补全边界而不是只框可见部分。这一点新手最容易做错只框可见部分会让模型学到的尺寸偏小。类别怎么定义类别粒度要一致。比如汽车这个类别是只包括轿车还是包括 SUV、面包车如果数据集里既有轿车又有卡车那就要么分成两类要么合并成一类车辆不能一部分标汽车一部分标卡车还指望模型自己区分。类别定义一旦定下整个数据集必须严格执行。3.2 单张图片的完整标注操作拿一张图走一遍完整流程把每个动作的意图讲清楚。打开 LabelImgOpen Dir选中图片目录第一张图加载出来后按W进入画框模式鼠标从目标左上角拖到右下角松开后弹出类别选择框选对应类别确认。一个目标标完继续下一个直到这张图所有目标都框完。这里有几个实操细节值得说。画框时先放大小目标在原始视图下很难框准Ctrl滚轮放大到目标占屏幕合适比例再画精度会高很多。框的顺序无所谓YOLO 标签不关心框的先后但养成从左到右、从上到下的习惯回头检查时更顺。标完一张立刻切下一张开了自动保存后按D直接走不要停下来欣赏节奏一断效率就掉。一张图标的合理时间熟练后普通场景 10 到 30 秒密集场景可能一两分钟。如果一张图你花了五分钟还在纠结某个模糊目标标不标说明规范没定清楚停下来回去补规范别硬标。3.3 大批量标注的节奏管理标数据集是马拉松不是短跑。我的经验是分批推进、定期抽检。一次连续标两小时以上后面错误率会明显上升建议每 45 分钟休息一下。更重要的是抽检机制。每标完 100 张随机抽 10 张回看检查框是否贴紧、类别是否正确、有没有漏标。发现系统性问题比如某个类别总是标松立刻停下来统一修正别等标完几千张才发现全错那时候返工成本是灾难性的。还有个小技巧把难标和易标的图分开。先用一批简单清晰的图快速推进建立手感和信心把模糊、密集、边界情况复杂的图单独挑出来集中处理处理时精力更集中判断也更准。3.4 从 VOC 到 YOLO 的格式转换如果你标成了 xml有时候团队里有人习惯用 VOC 格式标或者你接手的是别人标好的 xml 数据集就需要转成 YOLO 格式。虽然 LabelImg 能直接存 YOLO但转换脚本这个技能必须会因为实际项目里格式转换是家常便饭。转换的核心逻辑就三步读 xml 拿到框的左上右下坐标和图片宽高把(xmin, ymin, xmax, ymax)转成归一化的中心点和宽高按类别名映射成索引写进 txt。import os import xml.etree.ElementTree as ET from PIL import Image # 类别名到索引的映射顺序必须和 data.yaml 的 names 一致 classes [person, car, bicycle] class_to_id {name: i for i, name in enumerate(classes)} def convert_annotation(xml_path, img_path, out_txt_path): tree ET.parse(xml_path) root tree.getroot() # 读图片真实宽高这是归一化的基准 with Image.open(img_path) as im: w, h im.size lines [] for obj in root.iter(object): name obj.find(name).text if name not in class_to_id: continue # 跳过未定义类别避免索引错乱 bbox obj.find(bndbox) xmin float(bbox.find(xmin).text) ymin float(bbox.find(ymin).text) xmax float(bbox.find(xmax).text) ymax float(bbox.find(ymax).text) # 转中心点 宽高再归一化 x_center (xmin xmax) / 2.0 / w y_center (ymin ymax) / 2.0 / h bw (xmax - xmin) / w bh (ymax - ymin) / h lines.append(f{class_to_id[name]} {x_center:.6f} {y_center:.6f} {bw:.6f} {bh:.6f}) with open(out_txt_path, w) as f: f.write(\n.join(lines))这段脚本里有两个地方是新手最容易写错的。一是归一化基准必须用Image.open读每张图真实尺寸不能拿固定值。二是类别映射classes列表的顺序就是最终索引一旦定了就不能改改了所有标签都得重转。转换完一定要抽几张图可视化验证把框画回图上看看位置对不对别转完直接拿去训练。4. 标签质量校验与常见问题排查4.1 训练前的标签自检清单标签转完、数据集组织好别急着开训。先跑一遍自检把问题挡在训练之前。我整理了一份检查清单按这个顺序过一遍能拦掉九成以上的标签问题。检查项检查方法不合格表现图片标签一一对应对比两个目录的文件名集合有图无标签或有标签无图坐标范围合法脚本扫描所有值是否在 0~1出现负数或大于 1类别索引合法检查索引是否小于类别总数索引越界空标签文件存在统计空 txt 数量负样本缺文件框宽高非零检查 width/height 是否大于 0出现 0 宽高框类别分布合理统计各类别框数量某类极少或极多其中坐标范围和类别索引这两项用几行脚本就能扫完强烈建议每次转换后都跑一遍。import os def check_labels(label_dir, num_classes): problems [] for fname in os.listdir(label_dir): if not fname.endswith(.txt): continue path os.path.join(label_dir, fname) with open(path) as f: for line_no, line in enumerate(f, 1): parts line.strip().split() if not parts: continue if len(parts) ! 5: problems.append(f{fname}:{line_no} 字段数不对) continue cls int(parts[0]) vals [float(v) for v in parts[1:]] if cls 0 or cls num_classes: problems.append(f{fname}:{line_no} 类别索引越界 {cls}) if any(v 0 or v 1 for v in vals): problems.append(f{fname}:{line_no} 坐标越界 {vals}) if vals[2] 0 or vals[3] 0: problems.append(f{fname}:{line_no} 宽高为零) return problems跑完如果problems是空的标签基本就干净了。有输出就按提示逐条修别带着问题训练训练出来的模型精度上不去你还得回头怀疑是模型问题白白浪费时间。4.2 高频问题速查与解决实际标注和转换过程中有几类问题反复出现我把它们和对应解法整理成速查表遇到直接对号入座。现象可能原因解决办法训练报标签缺失图片无对应 txt补空 txt 或检查文件名框整体偏移归一化用了错误尺寸用每张图真实宽高重转框位置对但类别全错类别索引与 yaml 顺序不符统一 classes 顺序重转训练 loss 不降标签坐标越界或宽高为零跑自检脚本清理部分图不参与训练文件名含中文或空格批量重命名验证集指标异常低train/val 切分时图标签错位按图切分重新组织其中框整体偏移这个坑最典型。表现是训练能跑但预测出来的框总是偏一个固定方向或比例。根因几乎都是转换时归一化基准错了——要么用了固定尺寸要么读错了宽高。排查方法很简单随便挑一张图把转换后的 txt 反算回像素坐标和原图上的框对比一眼就能看出偏差。类别全错这个也很常见尤其是多人协作时。A 同学按[car, person]标B 同学按[person, car]标合并后索引全乱。解决办法是类别定义写进项目文档所有人从同一份classes.txt读LabelImg 的预定义类别也从这份文件导入从源头保证一致。4.3 预标注加速与人工修正的混合流程纯手工标几千张图时间成本太高。等你有了一批标注数据、训出一个能用的初版模型后就可以切到预标注 人工修正的模式效率能提升好几倍。具体做法是用初版模型对未标注的图跑推理把预测结果按 YOLO 格式写成 txt和图片一起放进 LabelImg 打开。LabelImg 会自动加载已有的 txt 并画出框你只需要检查、微调、删掉误检、补上漏检然后保存。因为大部分框模型已经画好了人工只做修正单张图耗时能从几十秒降到几秒。这个流程有两个注意点。一是预标注模型的精度要够如果初版模型漏检严重人工补框的工作量反而更大不如纯手工。一般 mAP 到 0.5 以上再上预标注比较划算。二是修正时要警惕确认偏误人看到模型画好的框容易默认它是对的草草扫一眼就过。建议修正时对每个框都问一句这个框贴紧了吗、类别对吗保持和纯手工一样的严格标准否则预标注引入的错误会悄悄污染数据集。提示预标注生成的 txt 一定要和原图同名同目录结构LabelImg 才能自动关联。如果打开后看不到框先检查 txt 文件名和图片名是否完全一致包括大小写。5. 数据增强前的标签一致性保障5.1 增强会不会破坏标签YOLOv5 内置了 Mosaic、随机缩放、色彩抖动等增强这些在训练时实时做标签会跟着变换不需要你手动处理。但如果你在标注阶段之后、训练之前自己做离线增强比如用脚本把图片翻转、旋转生成新样本就必须同步变换标签否则图和标签对不上训练直接崩。离线增强里水平翻转是最常用也最容易实现的一种。翻转图片后框的中心 x 坐标要变成1 - x_center宽高不变。这个变换很简单但很多人忘了同步改标签结果翻转后的图和原标签错位。def flip_label_horizontal(line): parts line.strip().split() cls parts[0] x, y, w, h map(float, parts[1:]) x 1.0 - x # 水平翻转中心 x 镜像 return f{cls} {x:.6f} {y:.6f} {w:.6f} {h:.6f}旋转、裁剪这类增强的标签变换就复杂得多涉及坐标旋转矩阵和边界裁剪稍不注意就出错。我的建议是——离线增强只做水平翻转这种简单可靠的复杂增强交给 YOLOv5 训练时内置处理省心又不容易错。5.2 类别不平衡的处理时机标注完统计一下类别分布如果发现某类特别少比如 1000 个人只有 20 个消防栓就要考虑处理。处理时机有两个标注阶段补数据或者训练阶段用增强和采样策略。标注阶段能补就补多找一些含稀有类别的图来标这是最根本的解法。如果实在找不到更多数据训练时可以用 YOLOv5 的类别权重或者过采样但这些是补救手段效果不如直接补数据。我的原则是——稀有类别样本数低于总样本 5% 时优先想办法补数据别指望训练技巧硬扛。6. 我个人踩过的几个坑说几个文档里不会写、但实际会遇到的坑。第一个是 LabelImg 的自动保存和手动保存混用。开了自动保存后切换图片会存但如果你在同一张图上改完框没切图就关软件改动可能丢。我的习惯是改完重要标注手动补一个CtrlS双保险。第二个是图片旋转信息EXIF。手机拍的图常带旋转标记LabelImg 显示时可能已经转正但读图脚本按原始像素读导致归一化基准和显示不一致框偏移。解决办法是标注前统一用脚本把 EXIF 旋转烧进像素消除这个隐患。第三个是文件名大小写。Windows 不区分大小写Linux 区分。在 Windows 上标好的IMG_001.jpg和img_001.txt到 Linux 训练环境可能匹配不上。统一用小写命名能避开这个跨平台坑。第四个是标注中途改类别名。标了一半发现类别名拼错了直接改data.yaml是不够的所有已标 txt 里的索引也得跟着改。所以类别名在开标前就要反复确认定下来就别动。这套流程走下来从 LabelImg 标注到 YOLOv5 能直接训练的干净数据集基本就是一条顺畅的流水线。真正花时间的从来不是画框本身而是格式对齐、质量校验和那些隐蔽的路径、编码、归一化问题。把自检脚本和规范提前做好后面训练阶段的很多玄学问题根本不会出现。 
长河君 · 2026/10/27 12:48:25 · 阅读 1.2k LabelImg标注到YOLOv5训练：格式转换与标签校验全流程
做目标检测这行的人几乎绕不开两个东西一个是训练框架另一个就是标注工具。YOLOv5 作为落地项目里出场率极高的检测框架它的数据入口标准其实非常明确——每张图对应一个同名的 txt 标签文件里面按类别 归一化中心x 归一化中心y 归一化宽 归一化高的格式逐行写目标框。而 LabelImg 就是把这个格式喂给 YOLOv5 之前最常用的一道手工工序。很多人第一次跑 YOLOv5 的train.py报错十有八九不是模型问题而是标签格式没对上要么是 VOC 的 xml 没转要么是坐标没归一化要么是类别名和data.yaml里的顺序错位。这篇内容就把 LabelImg 标注到 YOLOv5 可用标签这条链路完整拆开从工具选型、目录组织、标注规范、格式转换、批量校验到踩坑排查全部按实操顺序讲清楚。不管你是刚接触目标检测的学生还是要把一个自采数据集跑通的中小团队开发者都能照着这套流程直接复现少走几天弯路。1. 整体方案设计与工具选型思路1.1 为什么是 LabelImg 而不是别的标注工具标注工具这几年冒出来很多有在线的、有团队协作的、有带半自动预标注的。但落到 YOLOv5 这个具体场景LabelImg 依然是性价比最高的起点原因很实在。第一是输出格式直接对口。LabelImg 原生支持 Pascal VOC 的 xml 和 YOLO 的 txt 两种保存格式切到 YOLO 模式后画完框保存出来的就是归一化坐标的 txt和 YOLOv5 的标签规范完全一致中间不需要写转换脚本。这一点对新手极其友好省掉了最容易出错的一环。第二是轻量、离线、无依赖。它就是个 Python 写的桌面小工具装完就能用不联网也能标图片不出本地对数据隐私敏感的场景很合适。相比之下很多在线标注平台要把图传上去团队协作是方便了但数据流转的顾虑也多。第三是快捷键体系成熟。标数据集是个体力活一个几千张图的项目标注速度直接决定项目周期。LabelImg 的W画框、D下一张、A上一张、CtrlS保存这套组合熟练之后单手就能操作效率比很多花哨工具还高。当然它也有明显短板不支持多人协作、没有预标注、界面比较朴素。所以我的实际做法是——小数据集和冷启动阶段用 LabelImg 手工标等积累了几百张之后用训好的模型做预标注再人工修正这个混合策略后面会展开讲。1.2 YOLOv5 对标签的真实要求到底是什么很多人对 YOLO 标签格式的理解停留在五个数但真正决定你能不能跑通的是这几个细节。YOLOv5 的标签文件是每张图一个 txt文件名与图片同名扩展名不同放在与图片平行的labels目录下。txt 里每一行代表一个目标框格式为class_index x_center y_center width height其中后四个值全部是相对于图片宽高的归一化值范围 0 到 1保留六位小数左右即可。class_index是从 0 开始的类别索引必须和data.yaml里names列表的顺序严格对应。这里有个特别容易被忽略的点归一化的分母是当前这张图的实际宽高不是数据集的统一尺寸。也就是说如果你的图片尺寸参差不齐每张图的归一化基准都不一样LabelImg 在 YOLO 模式下会自动按当前图尺寸算这一点它处理得是对的。但如果你自己写脚本转换 VOC 到 YOLO就必须读每张图真实的width和height不能拿一个固定值去套否则框会整体偏移——这是新手转换脚本里最高频的 bug。还有一个隐性要求空标签的处理。如果一张图里没有目标负样本YOLOv5 期望存在一个空的 txt 文件而不是没有文件。有图无标签文件训练时会被当成标签缺失跳过或报错有空文件才被正确识别为负样本。LabelImg 在 YOLO 模式下如果一张图没画任何框就保存默认不会生成文件这个坑后面会讲怎么补。1.3 目录结构怎么组织才不返工标注阶段最忌讳的就是目录乱。我见过太多项目标到一半发现图片和标签对不上号回头整理花的时间比标注还多。推荐从一开始就按 YOLOv5 官方认可的结构来dataset/ ├── images/ │ ├── train/ │ └── val/ ├── labels/ │ ├── train/ │ └── val/ └── data.yaml关键原则是images 和 labels 两棵树的子目录名必须完全一致都叫 train、都叫 valYOLOv5 在训练时会自动把images/train/xxx.jpg映射到labels/train/xxx.txt。你只要保证这个平行关系路径配置就几乎不会出错。标注阶段的临时文件我习惯单独放一个raw/目录标完再按比例切分到 train 和 val。切分比例一般 8:2 或 9:1小数据集可以 7:3 保证验证集有足够样本。切分时要注意按图片切标签跟着图片走绝不能把同一张图的图和标签分到不同集合。提示目录名、文件名里尽量不要出现中文和空格。YOLOv5 底层读路径时对特殊字符的处理不够健壮中文路径在部分环境下会直接读不到文件这个坑非常隐蔽排查起来很费时间。2. LabelImg 环境搭建与核心配置细节2.1 安装方式的选择与取舍LabelImg 的安装有三条常见路线各有适用场景我按推荐度排一下。路线一pip 安装最省事。直接pip install labelimg装完命令行敲labelimg就能启动。适合绝大多数人尤其是 Windows 和 macOS 用户。缺点是某些系统上 Qt 依赖可能冲突如果启动报 Qt 相关错误就换路线二。路线二源码运行最可控。从仓库拉源码装好pyqt5和lxml依赖后python labelImg.py启动。适合需要改源码、加自定义功能的人比如你想改默认保存格式或者加个自动编号逻辑。路线三打包好的可执行文件最无脑。直接下载对应系统的可执行版本双击运行。适合完全不想碰 Python 环境的用户但版本可能偏旧。我个人的习惯是用 pip 装但固定一个已知稳定的版本。因为 LabelImg 更新不算频繁新版本偶尔会引入小问题固定版本能保证团队里每个人环境一致避免我这能存你那不能存的扯皮。# 推荐的基础安装 pip install labelimg # 如果遇到 Qt 报错先卸载再装指定版本 pip uninstall pyqt5 pyqt5-tools pip install pyqt55.15.92.2 启动后必须改的几个默认设置LabelImg 装完直接开标大概率会踩格式坑。启动后第一件事是进设置把几个关键项调对这几步花两分钟能省后面几小时。第一切换保存格式为 YOLO。界面左侧工具栏有个格式切换按钮默认是 PascalVOC点一下切到 YOLO。切换后保存出来的就是 txt 而不是 xml。这个一定要在开始标注之前切标到一半再切会导致前面存的格式和后面不一致混在一起非常麻烦。第二设置自动保存。菜单里勾选Auto Save mode这样每次切到下一张图时自动保存当前标注不用手动CtrlS。标几千张图的时候忘记保存丢掉的标注能让人崩溃这个开关强烈建议打开。第三配置预定义类别。在设置里找到Predefined Classes把你要标的类别一行一个写进去。这样画框时可以直接从下拉列表选类别不用每次手打既快又避免拼写不一致。类别名要和后面data.yaml里的names完全一致大小写都不能差。第四确认标注框颜色和显示。这个纯属体验优化但类别多的时候给不同类别配不同颜色能显著降低标错的概率尤其是相似类别比如货车和客车挨着出现时。2.3 快捷键体系与效率提升标注效率的核心就是少动鼠标。LabelImg 的快捷键我整理成一张表建议打印出来贴屏幕边上练熟之后速度能翻倍。操作快捷键说明画矩形框W最常用按下后拖拽画框下一张D标完一张立刻切下一张上一张A标错了回头改保存CtrlS开了自动保存可省略删除当前框Delete选中框后删除放大/缩小Ctrl滚轮小目标必用移动图片按住滚轮拖放大后平移查看复制上一张的框CtrlD连续相似场景提速神器其中CtrlD复制上一张标注框这个功能很多人不知道。在视频抽帧或者连续拍摄的场景里相邻帧的目标位置几乎一样复制过来微调比重新画快得多。我标过一个连续拍摄的数据集靠这个功能效率提升了差不多三倍。注意CtrlD复制的是上一张图的框如果两张图尺寸不同框的位置会有偏差复制后一定要检查微调不能无脑复制。3. 标注规范与实操全流程3.1 标注前的规范制定动手标之前先花半小时把规范定下来比标到一半再统一强一百倍。规范要明确三件事标什么、怎么标边界、类别怎么定义。标什么明确哪些目标要标、哪些忽略。比如做车辆检测远处的、被遮挡超过 70% 的、模糊到人眼都难辨的是标还是不标这些边界情况必须提前定规则。我的习惯是——遮挡超过 70% 或尺寸小于 10x10 像素的目标不标因为这类目标即使标了模型也学不好反而引入噪声。怎么标边界框要贴紧目标的外接矩形不能松也不能切。松了会把背景算进目标切了会丢失目标信息。对于有遮挡的目标框按可见部分的完整外接矩形来画被遮挡的部分靠推理补全边界而不是只框可见部分。这一点新手最容易做错只框可见部分会让模型学到的尺寸偏小。类别怎么定义类别粒度要一致。比如汽车这个类别是只包括轿车还是包括 SUV、面包车如果数据集里既有轿车又有卡车那就要么分成两类要么合并成一类车辆不能一部分标汽车一部分标卡车还指望模型自己区分。类别定义一旦定下整个数据集必须严格执行。3.2 单张图片的完整标注操作拿一张图走一遍完整流程把每个动作的意图讲清楚。打开 LabelImgOpen Dir选中图片目录第一张图加载出来后按W进入画框模式鼠标从目标左上角拖到右下角松开后弹出类别选择框选对应类别确认。一个目标标完继续下一个直到这张图所有目标都框完。这里有几个实操细节值得说。画框时先放大小目标在原始视图下很难框准Ctrl滚轮放大到目标占屏幕合适比例再画精度会高很多。框的顺序无所谓YOLO 标签不关心框的先后但养成从左到右、从上到下的习惯回头检查时更顺。标完一张立刻切下一张开了自动保存后按D直接走不要停下来欣赏节奏一断效率就掉。一张图标的合理时间熟练后普通场景 10 到 30 秒密集场景可能一两分钟。如果一张图你花了五分钟还在纠结某个模糊目标标不标说明规范没定清楚停下来回去补规范别硬标。3.3 大批量标注的节奏管理标数据集是马拉松不是短跑。我的经验是分批推进、定期抽检。一次连续标两小时以上后面错误率会明显上升建议每 45 分钟休息一下。更重要的是抽检机制。每标完 100 张随机抽 10 张回看检查框是否贴紧、类别是否正确、有没有漏标。发现系统性问题比如某个类别总是标松立刻停下来统一修正别等标完几千张才发现全错那时候返工成本是灾难性的。还有个小技巧把难标和易标的图分开。先用一批简单清晰的图快速推进建立手感和信心把模糊、密集、边界情况复杂的图单独挑出来集中处理处理时精力更集中判断也更准。3.4 从 VOC 到 YOLO 的格式转换如果你标成了 xml有时候团队里有人习惯用 VOC 格式标或者你接手的是别人标好的 xml 数据集就需要转成 YOLO 格式。虽然 LabelImg 能直接存 YOLO但转换脚本这个技能必须会因为实际项目里格式转换是家常便饭。转换的核心逻辑就三步读 xml 拿到框的左上右下坐标和图片宽高把(xmin, ymin, xmax, ymax)转成归一化的中心点和宽高按类别名映射成索引写进 txt。import os import xml.etree.ElementTree as ET from PIL import Image # 类别名到索引的映射顺序必须和 data.yaml 的 names 一致 classes [person, car, bicycle] class_to_id {name: i for i, name in enumerate(classes)} def convert_annotation(xml_path, img_path, out_txt_path): tree ET.parse(xml_path) root tree.getroot() # 读图片真实宽高这是归一化的基准 with Image.open(img_path) as im: w, h im.size lines [] for obj in root.iter(object): name obj.find(name).text if name not in class_to_id: continue # 跳过未定义类别避免索引错乱 bbox obj.find(bndbox) xmin float(bbox.find(xmin).text) ymin float(bbox.find(ymin).text) xmax float(bbox.find(xmax).text) ymax float(bbox.find(ymax).text) # 转中心点 宽高再归一化 x_center (xmin xmax) / 2.0 / w y_center (ymin ymax) / 2.0 / h bw (xmax - xmin) / w bh (ymax - ymin) / h lines.append(f{class_to_id[name]} {x_center:.6f} {y_center:.6f} {bw:.6f} {bh:.6f}) with open(out_txt_path, w) as f: f.write(\n.join(lines))这段脚本里有两个地方是新手最容易写错的。一是归一化基准必须用Image.open读每张图真实尺寸不能拿固定值。二是类别映射classes列表的顺序就是最终索引一旦定了就不能改改了所有标签都得重转。转换完一定要抽几张图可视化验证把框画回图上看看位置对不对别转完直接拿去训练。4. 标签质量校验与常见问题排查4.1 训练前的标签自检清单标签转完、数据集组织好别急着开训。先跑一遍自检把问题挡在训练之前。我整理了一份检查清单按这个顺序过一遍能拦掉九成以上的标签问题。检查项检查方法不合格表现图片标签一一对应对比两个目录的文件名集合有图无标签或有标签无图坐标范围合法脚本扫描所有值是否在 0~1出现负数或大于 1类别索引合法检查索引是否小于类别总数索引越界空标签文件存在统计空 txt 数量负样本缺文件框宽高非零检查 width/height 是否大于 0出现 0 宽高框类别分布合理统计各类别框数量某类极少或极多其中坐标范围和类别索引这两项用几行脚本就能扫完强烈建议每次转换后都跑一遍。import os def check_labels(label_dir, num_classes): problems [] for fname in os.listdir(label_dir): if not fname.endswith(.txt): continue path os.path.join(label_dir, fname) with open(path) as f: for line_no, line in enumerate(f, 1): parts line.strip().split() if not parts: continue if len(parts) ! 5: problems.append(f{fname}:{line_no} 字段数不对) continue cls int(parts[0]) vals [float(v) for v in parts[1:]] if cls 0 or cls num_classes: problems.append(f{fname}:{line_no} 类别索引越界 {cls}) if any(v 0 or v 1 for v in vals): problems.append(f{fname}:{line_no} 坐标越界 {vals}) if vals[2] 0 or vals[3] 0: problems.append(f{fname}:{line_no} 宽高为零) return problems跑完如果problems是空的标签基本就干净了。有输出就按提示逐条修别带着问题训练训练出来的模型精度上不去你还得回头怀疑是模型问题白白浪费时间。4.2 高频问题速查与解决实际标注和转换过程中有几类问题反复出现我把它们和对应解法整理成速查表遇到直接对号入座。现象可能原因解决办法训练报标签缺失图片无对应 txt补空 txt 或检查文件名框整体偏移归一化用了错误尺寸用每张图真实宽高重转框位置对但类别全错类别索引与 yaml 顺序不符统一 classes 顺序重转训练 loss 不降标签坐标越界或宽高为零跑自检脚本清理部分图不参与训练文件名含中文或空格批量重命名验证集指标异常低train/val 切分时图标签错位按图切分重新组织其中框整体偏移这个坑最典型。表现是训练能跑但预测出来的框总是偏一个固定方向或比例。根因几乎都是转换时归一化基准错了——要么用了固定尺寸要么读错了宽高。排查方法很简单随便挑一张图把转换后的 txt 反算回像素坐标和原图上的框对比一眼就能看出偏差。类别全错这个也很常见尤其是多人协作时。A 同学按[car, person]标B 同学按[person, car]标合并后索引全乱。解决办法是类别定义写进项目文档所有人从同一份classes.txt读LabelImg 的预定义类别也从这份文件导入从源头保证一致。4.3 预标注加速与人工修正的混合流程纯手工标几千张图时间成本太高。等你有了一批标注数据、训出一个能用的初版模型后就可以切到预标注 人工修正的模式效率能提升好几倍。具体做法是用初版模型对未标注的图跑推理把预测结果按 YOLO 格式写成 txt和图片一起放进 LabelImg 打开。LabelImg 会自动加载已有的 txt 并画出框你只需要检查、微调、删掉误检、补上漏检然后保存。因为大部分框模型已经画好了人工只做修正单张图耗时能从几十秒降到几秒。这个流程有两个注意点。一是预标注模型的精度要够如果初版模型漏检严重人工补框的工作量反而更大不如纯手工。一般 mAP 到 0.5 以上再上预标注比较划算。二是修正时要警惕确认偏误人看到模型画好的框容易默认它是对的草草扫一眼就过。建议修正时对每个框都问一句这个框贴紧了吗、类别对吗保持和纯手工一样的严格标准否则预标注引入的错误会悄悄污染数据集。提示预标注生成的 txt 一定要和原图同名同目录结构LabelImg 才能自动关联。如果打开后看不到框先检查 txt 文件名和图片名是否完全一致包括大小写。5. 数据增强前的标签一致性保障5.1 增强会不会破坏标签YOLOv5 内置了 Mosaic、随机缩放、色彩抖动等增强这些在训练时实时做标签会跟着变换不需要你手动处理。但如果你在标注阶段之后、训练之前自己做离线增强比如用脚本把图片翻转、旋转生成新样本就必须同步变换标签否则图和标签对不上训练直接崩。离线增强里水平翻转是最常用也最容易实现的一种。翻转图片后框的中心 x 坐标要变成1 - x_center宽高不变。这个变换很简单但很多人忘了同步改标签结果翻转后的图和原标签错位。def flip_label_horizontal(line): parts line.strip().split() cls parts[0] x, y, w, h map(float, parts[1:]) x 1.0 - x # 水平翻转中心 x 镜像 return f{cls} {x:.6f} {y:.6f} {w:.6f} {h:.6f}旋转、裁剪这类增强的标签变换就复杂得多涉及坐标旋转矩阵和边界裁剪稍不注意就出错。我的建议是——离线增强只做水平翻转这种简单可靠的复杂增强交给 YOLOv5 训练时内置处理省心又不容易错。5.2 类别不平衡的处理时机标注完统计一下类别分布如果发现某类特别少比如 1000 个人只有 20 个消防栓就要考虑处理。处理时机有两个标注阶段补数据或者训练阶段用增强和采样策略。标注阶段能补就补多找一些含稀有类别的图来标这是最根本的解法。如果实在找不到更多数据训练时可以用 YOLOv5 的类别权重或者过采样但这些是补救手段效果不如直接补数据。我的原则是——稀有类别样本数低于总样本 5% 时优先想办法补数据别指望训练技巧硬扛。6. 我个人踩过的几个坑说几个文档里不会写、但实际会遇到的坑。第一个是 LabelImg 的自动保存和手动保存混用。开了自动保存后切换图片会存但如果你在同一张图上改完框没切图就关软件改动可能丢。我的习惯是改完重要标注手动补一个CtrlS双保险。第二个是图片旋转信息EXIF。手机拍的图常带旋转标记LabelImg 显示时可能已经转正但读图脚本按原始像素读导致归一化基准和显示不一致框偏移。解决办法是标注前统一用脚本把 EXIF 旋转烧进像素消除这个隐患。第三个是文件名大小写。Windows 不区分大小写Linux 区分。在 Windows 上标好的IMG_001.jpg和img_001.txt到 Linux 训练环境可能匹配不上。统一用小写命名能避开这个跨平台坑。第四个是标注中途改类别名。标了一半发现类别名拼错了直接改data.yaml是不够的所有已标 txt 里的索引也得跟着改。所以类别名在开标前就要反复确认定下来就别动。这套流程走下来从 LabelImg 标注到 YOLOv5 能直接训练的干净数据集基本就是一条顺畅的流水线。真正花时间的从来不是画框本身而是格式对齐、质量校验和那些隐蔽的路径、编码、归一化问题。把自检脚本和规范提前做好后面训练阶段的很多玄学问题根本不会出现。