简介LabelImg是一款面向计算机视觉目标检测任务的可视化图像标注工具主要服务于Faster R-CNN、YOLO、SSD等主流网络的训练数据准备用户通过框选即可标注目标位置与类别并输出遵循PASCAL VOC规范的XML标注文件是制作检测数据集的关键辅助软件。压缩包内共收录127个文件大小约6.39MB其中44个Python文件构成核心逻辑38张PNG图片及多组SVG素材支撑界面显示还包含Shell脚本、配置文件、Markdown文档等能覆盖环境配置、启动运行和二次开发场景在Python加上lxml的依赖环境下即可使用。目前已有357人学习/下载适合因GitHub访问不便而需要本地源码包的开发者。该源码包不仅提供离线启动方案还能供读者深入研读标注框绘制、类别管理、XML读写等关键模块配合demo图片可快速理解交互流程便于后续定制功能或迁移集成到其他项目中。1. labelImg-master.rar 是什么从解压开始的一张图像标注工作台如果你手上正握着一个labelImg-master.rar压缩包那大概率已经走到了目标检测项目的数据准备阶段——图像有了缺的是标注文件。这个压缩包解压后就是一套基于 Python 和 Qt 开发的图像标注工具用鼠标在图片上拉矩形框给每个框贴上类别名存成标准的 PascalVOC XML 或 YOLO TXT 格式。它解决的是目标检测、图像分割类任务里最原始也最绕不开的问题把图片里的物体位置“翻译”成模型能读懂的坐标。无论是用 YOLO 训练自己的检测器还是给某跨平台系统的视觉模块做准备标注环节几乎都会遇到它。这篇笔记就顺着这个压缩包从解压讲到进阶适合刚接触标注的初学者也适合想梳理格式转换与批量处理细节的熟手。2. 解压与运行环境拿到压缩包后先别急着双击2.1 压缩包里的目录结构先认全再动手解压labelImg-master.rar后你会看到一个典型的 Python 开源项目布局。首先要认得主程序入口labelImg.py这是整个工具的启动文件。旁边会有libs/和data/两个目录前者装的是 Qt 界面组件、画框逻辑、格式读写等核心模块后者存放默认的类别标签文件。还有一个容易被忽略的resources.py它是界面图标和样式资源的编译产物如果运行时提示缺少某些资源问题通常出在这个文件的加载上。整体结构并不复杂但知道每个目录的职责后续排错会方便很多。常见目录结构大致如下labelImg-master/ ├── labelImg.py # 主程序入口 ├── libs/ # UI 组件、画框与标注逻辑 ├── data/ # 预定义标签文件、示例配置 ├── resources.py # 图标等资源文件 └── requirements.txt # Python 依赖清单2.2 Windows 上跑起来的最小命令序列在 Windows 上启动 labelImg最快的方式有两个直接用 Release 里打包好的 exe或者装 Python 环境跑源码。很多时候你手里的压缩包是源码版那就走下面的命令。先创建虚拟环境再装依赖然后启动。# 1. 在压缩包解压目录里创建虚拟环境 python -m venv .venv # 2. 激活虚拟环境Windows 下 .venv\Scripts\activate.bat # 3. 安装依赖PyQt5 是界面库缺它启动必报错 pip install PyQt5 # 4. 启动主程序 python labelImg.py这里要说明两点。第一requirements.txt里通常只列了 PyQt5但如果你要处理的是标准 JPEG 和 PNG 图片PyQt5 自带的图像插件基本够用如果图片格式比较偏门建议顺手pip install opencv-python可以避免一些奇怪的编码格式打不开。第二启动后界面出现了但窗口里没有图片是正常的——你需要用菜单里的“Open Dir”指定图片目录这个动作不要省略。2.3 Linux 与 macOS 上的两个关键差异在 Linux 环境比如 Ubuntu下依赖安装多了一步系统库的坑点。PyQt5 虽然能通过 pip 装上但界面渲染依赖 xcb 相关库缺了会报could not connect to display或插件加载错误。我的习惯是先装系统级依赖再装 Python 包能省去很多排错时间。# Ubuntu/Debian 下先装系统库再装 Python 依赖 sudo apt-get install libxcb-xinerama0 libxcb-cursor0 pip install PyQt5 python labelImg.pymacOS 下主要是启动方式的差异。由于 macOS 的窗口管理和 App 权限策略直接用python labelImg.py有时候会出现窗口打不开或菜单栏不响应的情况。常见的做法是右键点击源文件用 Python Launcher 运行或者在终端里从源码目录启动。另外 macOS 上鼠标滚轮的缩放方向默认与 Windows 相反第一次用会有明显的“不跟手”感适应几分钟就好。3. 进入标注界面、流程与快捷键要一次吃透3.1 第一次打开界面先理解几个关键区域启动 labelImg 后界面分成几个功能性区域。顶部是菜单栏和工具栏左边主区域是图像画布右下角是文件列表左下角是标注框的坐标信息。菜单里的“PascalVOC”和“YOLO”是两种输出格式的切换开关默认是 PascalVOC也就是 XML 格式改用 YOLO 训练时记得切成 YOLO否则出来的标注文件模型不认。界面右侧的框选列表显示当前图片上已有的标注框点击任意框可以在图片上高亮并选中它方便修改或删除。左下角会实时显示当前选中框的x1, y1, x2, y2坐标。对新手来说最容易忽略的是底部“Save Dir”和“Image Dir”的区别。Image Dir 是图片来源目录Save Dir 是标注文件的输出目录——这两个目录没有自动关联如果保存后发现标注文件找不到八成是 Save Dir 没有提前设定文件被写到了默认位置。3.2 完整标注流程画框—命名—保存—切换一套标准的标注流程并不复杂但节奏要稳定。先创建类别列表文件classes.txt一行写一个类别名比如cat、dog、person然后在界面里通过 “Open Dir” 选中图片目录“Change Save Dir” 选中输出目录。切到“PascalVOC”格式后从第一张图开始按顺序执行以下操作。# classes.txt 示例内容每行一个类别不含序号和空格 cat dog person画框的操作序列是点工具栏上的“Create RectBox”按钮或者直接按快捷键W鼠标变成十字形在图片上按住左键拖动拉到合适大小后松开会弹出一个类别选择框输入或选择类别名确认即可。如果想删掉画错的框点框使其高亮然后按Del键。单张图完成后按CtrlS保存当前标注文件再按D切到下一张继续。完整标注一轮的操作序列用快捷键表述 W 画框 → 输入类别名确认 → CtrlS 保存 → D 切到下一张这套操作里最容易被忽视的是“每个类别框尽量贴合物体边缘”的原则。比如标注一个站在路边的行人框的下边界应该落在脚底而不是多留出半米地面上边界贴头顶左右贴身体轮廓。模型训练出来能不能精准定位取决于训练数据的框质量而不只是画得快不快。3.3 必须背下来的快捷键表labelImg 的快捷键设计有明确的效率逻辑左手管键盘切换右手管鼠标画框。常用的组合如下表快捷键作用替代鼠标操作W新建矩形框点击 Create RectBoxD / A切换下一张 / 上一张图点击 Next / PrevCtrlS保存标注文件点击 SaveDel删除当前选中的框无Ctrl滚轮缩放图像无滚轮上下滚动文件列表双击文件名换图标注效率的高低很大程度取决于能不能做到“双手不离键盘”。A 同学第一次用 labelImg 时全程用鼠标点按钮标了 200 张图花了半天改成快捷键之后同样数量只需要两小时。差距不在手速而在操作习惯。3.4 标注原则什么框算合格有几个原则是我在多次项目里验证过且不会妥协的。第一矩形框必须是目标物体的最小外接矩形。多出几个像素会引入背景噪声少几个像素会切掉物体边缘。这个标准在任何数据集里都适用。第二小目标、遮挡目标不要凭想象补全。图片上只能看到半辆车框就框可见的部分一辆车被树挡住三分之一框也只框出露出的主体。强行补全会让模型学到错误的形状先验尤其对检测小目标有负面影响。第三类别的定义要提前固化。同一个项目里标注员之间必须统一标准。比如“person”类别是只包括完整的人还是包括骑车的人“cat”是包括猫头特写还是全身照这些标准应该在标注开始前写进一页文档里而不是边标边猜。4. 标注结果的格式与转换VOC 和 YOLO 你都得会用4.1 PascalVOC 格式的结构解析使用 labelImg 时如果保持默认的 PascalVOC 格式保存出的每张图片对应一个同名.xml文件。这个 XML 的核心价值在于它把矩形框的坐标、类别和图片尺寸都结构化存储训练脚本可以直接按节点读取。annotation folderimages/folder filename000001.jpg/filename size width1920/width height1080/height depth3/depth /size object namecat/name bndbox xmin124/xmin ymin205/ymin xmax482/xmax ymax510/ymax /bndbox /object /annotation理解这个结构至少能解决两个常见问题。一是图宽高与坐标单位不匹配——打标注时改了图像尺寸但 xml 里记录的还是旧宽高训练读出的坐标就会漂移二是类别名不一致——name节点里的值必须与训练时的类别配置一字不差Cat和cat是两个完全不同的类。在数据量大的项目里这类错误最隐蔽也最浪费排查时间。4.2 转成 YOLO 格式脚本与归一化计算如果你要用 YOLO 系列模型训练VOC 的 XML 格式不能直接用得转成 YOLO 要求的 TXT 格式。每个.xml对应一个同名.txt每行格式是类别id x_center y_center width height四个数值都要归一化到 0~1 之间分母是图片原始宽高。下面这个脚本是常见做法可以直接替换文件路径后使用import os import xml.etree.ElementTree as ET def convert_voc_to_yolo(xml_path, out_dir, class_list): tree ET.parse(xml_path) root tree.getroot() img_w int(root.find(size/width).text) img_h int(root.find(size/height).text) txt_path os.path.join(out_dir, os.path.splitext(os.path.basename(xml_path))[0] .txt) lines [] for obj in root.iter(object): name obj.find(name).text if name not in class_list: continue cls_id class_list.index(name) box obj.find(bndbox) xmin float(box.find(xmin).text) ymin float(box.find(ymin).text) xmax float(box.find(xmax).text) ymax float(box.find(ymax).text) x_center (xmin xmax) / 2.0 / img_w y_center (ymin ymax) / 2.0 / img_h width (xmax - xmin) / img_w height (ymax - ymin) / img_h lines.append(f{cls_id} {x_center:.6f} {y_center:.6f} {width:.6f} {height:.6f}) with open(txt_path, w) as f: f.write(\n.join(lines)) # 使用示例 class_list [cat, dog, person] os.makedirs(yolo_labels, exist_okTrue) xml_dir voc_xml for file in os.listdir(xml_dir): if file.endswith(.xml): convert_voc_to_yolo(os.path.join(xml_dir, file), yolo_labels, class_list)脚本的逻辑不难但有三个参数值得注意。一是class_list的顺序必须与训练时的配置文件一致因为 YOLO 只认类别 ID 不认类别名二是归一化坐标用x_center和width不是xmin和xmax初学者最容易在这里写错三是if name not in class_list: continue这行目的是过滤掉没有在类别清单里出现的目标防止脏数据进入训练集。4.3 标注质量自检脚本边标边验标注做完不等于数据可用。常见的情况是某张图漏标了目标、类别名写错、坐标超出图片边界。手工检查上千张图不现实一个小脚本可以帮你过滤大部分问题。import os import xml.etree.ElementTree as ET from PIL import Image def verify_voc(img_dir, xml_dir): errors [] for xml_file in os.listdir(xml_dir): if not xml_file.endswith(.xml): continue xml_path os.path.join(xml_dir, xml_file) tree ET.parse(xml_path) root tree.getroot() # 检查图片是否缺失或尺寸不匹配 img_name root.find(filename).text img_path os.path.join(img_dir, img_name) if not os.path.exists(img_path): errors.append(f{xml_file}: 图片不存在 {img_name}) continue img Image.open(img_path) w, h img.size xml_w int(root.find(size/width).text) xml_h int(root.find(size/height).text) if (w, h) ! (xml_w, xml_h): errors.append(f{xml_file}: 尺寸不一致 xml({xml_w},{xml_h}) img({w},{h})) # 检查坐标是否越界 for obj in root.iter(object): name obj.find(name).text box obj.find(bndbox) xmin float(box.find(xmin).text) ymin float(box.find(ymin).text) xmax float(box.find(xmax).text) ymax float(box.find(ymax).text) if xmin 0 or ymin 0 or xmax w or ymax h: errors.append(f{xml_file}: 坐标越界 {name} ({xmin},{ymin},{xmax},{ymax})) return errors # 输出所有发现的问题 for e in verify_voc(images, voc_xml): print(e)这个脚本做了两件核心检查图片尺寸一致性检查和坐标越界检查。尺寸不一致的来源通常是图片预处理重设了大小但没更新 XML坐标越界来源多是画框时拉到画布边缘外虽然界面能保存但数值已经超界。运行一次后把报错的文件挑出来人工复查即可。实际用下来这类脚本能过滤掉一半以上的低级错误。5. 避坑labelImg 使用中最常见的 5 个翻车现场标注工具本身不算复杂但真用起来各种稀奇古怪的问题还是会遇到。下面这些坑是我自己踩过、也在项目里帮别人排查过的按现象和解决方式拆开讲。5.1 启动后报“No module named PyQt5”环境没配对现象在解压目录里直接执行python labelImg.py终端报ModuleNotFoundError: No module named PyQt5。原因压缩包里的源码依赖 PyQt5但当前 Python 环境还没有安装。还有一种是装了依赖但装在别的虚拟环境或全局环境里当前终端激活的环境不对导致找不到。解决先pip install PyQt5安装完确认一下当前环境是激活状态。更稳妥的做法是像前面第 2 章那样用虚拟环境隔离避免多个项目互相污染。pip install PyQt5 python -c from PyQt5.QtWidgets import QApplication; print(ok)输出ok说明环境正常再执行python labelImg.py。如果输出报错就看提示缺哪个具体模块缺什么装什么。5.2 标注文件保存了但找不到Save Dir 没设置现象按CtrlS保存界面提示已保存但在图片目录里找不到.xml或.txt文件。原因labelImg 的保存路径和图片路径是两套逻辑。默认情况下保存文件可能写到了主程序目录或上一次使用的目录并不会因为打开图片目录就自动跟着走。解决打开图片目录后第一件事就是在菜单里点 “Change Save Dir” 选定输出目录再开始标注。这是新手最容易翻车的一个点没有之一。5.3 打开某张图片卡死图像尺寸过大现象图片列表切换到某张图时界面长时间无响应甚至直接无响应退出。原因相机原图或高分辨率拼接图的尺寸常常达到几千像素长边而 labelImg 默认会把整张图加载进内存同时绘制画布和标注层内存占用会瞬间飙升。解决标注前先做一次图片批量缩放。常见做法是把长边缩到 2000 像素以内短边对应等比例缩放这样既保证标注精度不再无限放大细节又避免卡死。# 用 Python PIL 批量缩放图片覆盖写入前先备份 from PIL import Image import os for f in os.listdir(images): if f.endswith(.jpg): img Image.open(os.path.join(images, f)) if max(img.size) 2000: img.thumbnail((2000, 2000)) img.save(os.path.join(resized, f))5.4 保存了两张图但输出的 TXT 内容完全相同现象用 YOLO 格式保存时连续几张图的.txt文件里标注内容一模一样或者文件内容与当前图片不符。原因labelImg 在 YOLO 模式下如果图片目录和标注文件目录不一致或者没有正确切换到 YOLO 模式就保存会沿用上一次的标注内容直接写到新文件。这个行为在旧版本上更容易出现。解决保存前先确认当前界面上显示的图片确实是你正在标注的那张再确认底部状态栏显示的是 YOLO 而不是 PascalVOC。切换格式的入口在菜单栏不是工具栏。5.5 切换下一张时速度很慢卡在加载上现象按D键切换下一张图界面停顿两三秒才显示图片。原因labelImg 每次切换图片都会重新创建画布和加载文件。如果图片目录里有大量高分辨率图片、内存条又紧张卡顿会被放大。解决除批量缩放外可以考虑分目录标注——一个目录放 200~300 张标注完一批再换下一批避免一个超大目录从头翻到尾。这样既能保证切换流畅也方便中途核对标注进度。6. 进阶让标注从手工活变成半自动流水线当图片量从几百张涨到几千张时纯手工标注的效率会变成瓶颈。一个现实的进阶路径是先用已有的检测模型对未标注图片做预标注再在 labelImg 里人工修正。操作上并不复杂。先把训练好的模型推理结果写成一个成 yolo 格式的 txt 文件然后用 labelImg 打开“预标注目录”和“图片目录”。它支持加载预标注的 txt 文件把模型画的框显示出来你只需要删掉误检、补上漏检、修正框边界。相比从零开始画能省掉一半以上的时间。我一般的流程是模型预标注 → labelImg 打开预标注文件 → 人工修正 → 另存为正式标注。注意修正后必须重新保存并且在保存时确认格式与类别名没有改动。如果数据集涉及多类别存在类别不平衡预标注时对少数类多做一些过采样会有助于模型稳定检出那些冷门目标。再补充一个常用小技巧如果你想快速验一版标注效果不必一上来就全量标注。先随机挑 50 张标出来跑一次训练看一眼 mAP 和漏检情况再决定要不要继续扩大数据量。对于小数据集这一条能帮你省下整晚的标注时间。labelImg 这套工具我前后用了三四年从最早的 Windows 源码版到现在的 Releases 版本踩过不少坑最后留下来的是两个习惯一个是在开始标注前永远先把目录结构、格式、类别清单这一整套配置固定下来另一个是标完一批数据立刻用自检脚本跑一遍不把带病数据留到训练时才暴雷。这两个习惯帮我在后续训练阶段省了大量返工的时间。希望帮到你。本文还有配套的精品资源点击获取
