labelImg图像标注全指南：安装部署、XML标注与YOLO格式转换

简介这份压缩包内含开源图像标注工具 labelImg 的完整工程源码面向计算机视觉开发者和研究人员提供一套可运行、可定制的图像标注方案。该工具支持在 Windows、macOS、Linux 等主流系统上运行能够快速绘制边界框和多边形区域为检测、分割等模型训练准备高质量标注数据。包内共一百一十八个文件以 Python 编写的核心程序为主承担图形界面、鼠标交互与坐标导出等关键逻辑同时配置有安装脚本、参数文件、图标资源以及 Shell 辅助脚本文件类型涵盖 Python 源码、PNG/SVG 图片、ICNS 图标和多种文本配置。整包约 6.95MB目录结构清晰兼顾运行、二次开发与版本管理。通过研读这些源码和配置读者可以完整理解图像标注工具从界面布局、图形绘制到标注结果保存的底层工作方式也能熟悉打包发布、资源编译等工程实践在此基础上还可按需求增加自定义标注类别或调整输出以适配主流数据集格式。目前已有七百零四人学习下载对需要快速搭建标注环境或深入研究标注工具实现细节的入门及进阶用户都很有价值。1. 把 labelImg 装好、用起来图像标注的第一步做过目标检测的人大概率绕不开 labelImg 这个名字。它不是一个复杂的产品就是一个开源的图像标注工具核心功能就两件事在图上画矩形框或多边形再把框的坐标和类别写成 XML 或 TXT。这个 labelImg-master 压缩包我拆过不止一次里面装的是完整源码不是编译好的安装包动手能力强的可以直接跑不想碰源码的也可以用它自带的安装方式快速部署。适合的人群很明确准备做 YOLO、SSD、Faster R-CNN 训练的算法工程师需要手动给数据集打框标注的标注员以及想在自己业务里集成标注流程的开发者。这篇笔记会把源码包里每一类文件干什么用、三种操作系统怎么部署、标注流程怎么走、最容易翻车的坑在哪里一次讲清楚。2. 源码包里的东西先分清哪些能用、哪些不能动上手之前先把压缩包的构成摸清楚。很多人上来就找 exe 或 dmg结果发现全是 .py、.cfg、.in 这种文件心里就打鼓。其实这份资源定位就是「源代码分发包」不是绿色免安装版理解这个定位后面的路就顺了。2.1 六个关键文件的职责压缩包里最核心的启动文件是labelImg.py这个文件实现了整套图形界面和标注逻辑。它依赖 PyQt5 做窗口渲染通过canvas.py处理鼠标交互画矩形和调整框的位置全靠它。你要做的事情基本都在这个文件里想改窗口标题、默认尺寸、保存目录第一站就是这里。setup.py和setup.cfg是 Python 打包安装的入口。setup.py负责注册包的元数据和依赖关系执行pip install .时它决定要装哪些模块setup.cfg里存的是 wheel 构建配置包括项目版本号、作者信息、依赖列表这些在打 pip 包时会被读走。MANIFEST.in负责在打包分发时把非 Python 文件一起带上比如resources.py里引用的图标、主题文件和.ui界面定义文件缺了它打出来的 wheel 经常会出现「图标找不到」的诡异问题。.gitignore是版本控制用的跟运行时无关。它把编译产物、缓存目录、标注中间文件排除在 Git 追踪之外防止仓库被垃圾文件灌爆。使用者不需要动它除非你想把这个项目 fork 出去维护自己的版本。LICENSE文件声明了使用边界。labelImg 采用 MIT 许可证意味着你可以改、可以商用、可以闭源分发但原作者的版权声明要保留。如果你们公司要做商业标注平台拿这份源码改完也要带着 LICENSE 一起走。2.2 resources.py 和界面资源最容易忽略的依赖resources.py本质上是一个由.qrc资源文件编译出来的 Python 模块里面是用 base64 编码过的图标、样式表和界面布局数据。labelImg.py在启动时会import resources如果这个文件缺失、损坏或者版本不匹配启动时会直接抛ModuleNotFoundError或者AttrError而且报错指向的还不是真正的资源文件排查起来很绕。我一般不建议手工改resources.py因为它是编译产物改起来容易把自己绕晕。更稳妥的做法是用 PyQt5 自带的pyrcc5工具重新编译.qrc文件命令在对应系统小节里会给到。除非你只是日常做标注完全不需要碰它知道它是什么、出问题怎么重建就够了。2.3 demo 图片和 issue 模板验证安装用的包里附带了几张示例图片demo.jpg和demo3.jpg是普通照片test.512.512.bmp是一张 512x512 的测试位图臉書.jpg是一张中文文件名的图。这几张图的实际用途是帮你验证安装是否成功装完之后可以从任意目录加载图片如果 demo 能正常画框保存说明环境是通的。issue_template.md是 GitHub 上的问题模板给开发者提 issue 用的跟你本地使用无关。它存在的意义是规范 bug 报告格式比如要填操作系统版本、Python 版本、PyQt 版本、报错截图。你自己用不到但如果后续给上游提 issue可以参考它的字段。3. 三种操作系统部署从 Python 环境到首次启动源码包要跑起来第一步是把依赖环境搭好。labelImg 的依赖核心是 Python 3.8、PyQt5 和 Pillow其中 PyQt5 的版本选择决定了后面会不会闪退这一步值得花点时间。3.1 Windows 部署步骤Windows 上最省心的方式是用 pip 装依赖加启动源码。打开 PowerShell 或 CMD按顺序执行cd labelImg-master python -m venv venv venv\Scripts\activate pip install -r requirements.txt python labelImg.py这里先创建虚拟环境是习惯问题很多人在全局环境里装 PyQt5装完发现跟公司别的项目冲突所以隔离是最稳的。requirements.txt里通常固定了 PyQt5 和 Pillow 的版本区间如果用pip install PyQt5 Pillow直接装也能跑但版本漂移是个隐患新版本 PyQt5 在某些 Windows 显卡驱动下会出现界面绘制残缺。启动后窗口弹出是黑色的、按钮上的图标是空的说明resources.py没有正确加载。常见做法是手动编译一次资源文件命令如下pip install pyqt5-tools pyrcc5 -o libs/resources.py resources.qrc python labelImg.py编译完成后图标和主题恢复正常。这里的工作机制是把所有图片、样式、UI 定义打包成一个 Python 模块运行时直接读内存不依赖外部图片文件所以resources.py的体积偏大是正常的。3.2 Ubuntu 20.04/18.04 部署步骤Linux 上最容易掉的坑是系统自带的 Python 版本过旧以及缺少 PyQt5 的系统级依赖库。以 Ubuntu 20.04 为例sudo apt-get install python3-pyqt5 pyqt5-dev-tools cd labelImg-master python3 -m venv venv source venv/bin/activate pip install -r requirements.txt python labelImg.pypython3-pyqt5这个系统包非常关键因为 PyQt5 底层依赖 Qt 的 XCB 平台插件这部分通常不会通过 pip 完整带过来。如果你装上之后输入python labelImg.py报错qt.qpa.plugin: Could not load the Qt platform plugin xcb说明系统的 Qt 平台插件缺失。解决方式不是重装 PyQt5而是安装系统级依赖sudo apt-get install --reinstall libxcb-xinerama0 libxcb-cursor0Ubuntu 18.04 上还有一个注意点默认的 Python 3.6 在新版 PyQt5 下兼容性较差建议先升级到 Python 3.8 再跑。你可以用sudo apt install python3.8 python3.8-venv安装后手动指定解释器创建虚拟环境python3.8 -m venv venv source venv/bin/activate3.3 macOS 部署与 Makefile 的作用macOS 上一般直接用提供的Makefilecd labelImg-master make qt5py3 python labelImg.pyMakefile做的事就是把 PyQt5 的依赖装好然后执行pyrcc5编译资源文件。如果你的机器上先装了 Python 2 又装了 Python 3make命令可能调用了错误的解释器这时候手动指定make PYTHONpython3 qt5py3macOS 上最容易碰到的现象是右键菜单点不动或者画框时鼠标偏移这通常跟 macOS 的 Retina 缩放有关。可以在启动前设置环境变量禁用高 DPI 缩放export QT_AUTO_SCREEN_SCALE_FACTOR0 python labelImg.py如果你的标注屏幕是 4K 外接显示器这一步基本必备。4. 开始标注把第一张图的边界框写成 XML工具能启动只是第一步真正要解决的是标注效率和格式正确性。这一章把从加载图片到保存 XML 的完整链路走一遍同时把背后的格式约定讲透。4.1 界面功能区域与标注流程启动后界面上方是菜单栏和工具栏中间是图片显示区右侧是标注列表和标签列表。打开一张图片后按W键进入画框模式按住鼠标左键拖出一个矩形松开后弹出类别输入框填入类别名后按回车框就固定住了。如果想画多边形按CtrlW切换多边形模式逐点点击轮廓双击闭合。流程上最常见的做法是点左侧“打开目录”选择存放图片的文件夹按W或CtrlW开始画框每个对象画完框后输入类别名按CtrlS保存 XML 到指定目录按D跳到下一张继续标注其中打开目录这个动作是必需的它给工具指定了图片序列后面翻页、批量处理都依赖这个目录索引。类别名在整个 session 里会被记录第二次输入同一个类别时会有自动补全这个功能来自labelImg.py里的labelDialog.py模块它会维护一个当前会话的类别历史。4.2 Pascal VOC XML 的结构解析保存出来的 XML 格式是 PASCAL VOC 标准。打开一张标注好的 XML里面有一个关键节点bndboxannotation folderimages/folder filenamedemo.jpg/filename path/home/user/images/demo.jpg/path sourcedatabaseUnknown/database/source size width500/width height400/height depth3/depth /size segmented0/segmented object namecat/name poseUnspecified/pose truncated0/truncated difficult0/difficult bndbox xmin100/xmin ymin80/ymin xmax220/xmax ymax210/ymax /bndbox /object /annotation这里最需要注意的是filename、path和size三个字段。size里的宽高必须是原始图片的实际像素值有些训练框架比如早期的 YOLOv3 解析脚本会拿它做归一化计算如果图片被 resize 过标注坐标就全错了。path字段经常被忽略但很多转 COCO 格式的脚本会按path拼接图片路径如果你把数据集挪了位置最好批量改path而不是手工一张张弄。保存 XML 的默认方式是每个图片一个同名 XML 文件这是最普遍的工作方式。工具也支持自动保存模式编辑偏好里勾选「自动保存」后切到下一张图时自动写盘不用手按CtrlS。4.3 把 XML 转成 YOLO 训练格式手工标注只是准备阶段的工作训练阶段还需要把 VOC 的坐标换算成 YOLO 需要的归一化中心坐标格式而这时用脚本处理比手工计算更快import xml.etree.ElementTree as ET def convert_voc_to_yolo(xml_file, class_list): tree ET.parse(xml_file) root tree.getroot() width int(root.find(size/width).text) height int(root.find(size/height).text) for obj in root.findall(object): name obj.find(name).text if name not in class_list: continue xmin float(obj.find(bndbox/xmin).text) xmax float(obj.find(bndbox/xmax).text) ymin float(obj.find(bndbox/ymin).text) ymax float(obj.find(bndbox/ymax).text) x_center (xmin xmax) / 2.0 / width y_center (ymin ymax) / 2.0 / height box_width (xmax - xmin) / width box_height (ymax - ymin) / height class_id class_list.index(name) print(f{class_id} {x_center:.6f} {y_center:.6f} {box_width:.6f} {box_height:.6f}) class_list [cat, dog, person] convert_voc_to_yolo(demo.xml, class_list)这段脚本的关键点在于xmin、xmax等坐标必须从 XML 里读出来换算时做浮点除法不能直接用整数相除以免精度丢失。class_list的顺序决定了类别 ID 的分配训练时用的类别文件必须跟这里一致否则框会全部错位。5. 标注避坑指南闪退、乱码、坐标偏问题都在这用 labelImg 时间长了各种奇奇怪怪的问题都会遇到。东西本身不复杂但问题的外在表现往往掩盖了真正原因这里把最常见的几类问题整理出来按现象、原因、解决三步拆开。5.1 启动后马上闪退现象双击python labelImg.py后窗口闪了一下就退出终端里没有任何报错或者只留下一行Segmentation fault。原因绝大多数情况是 PyQt5 版本跟操作系统图形库不匹配尤其常见于 Windows 上安装了过新的 PyQt56.x 版本而labelImg.py的代码是按 PyQt5 的 API 写的。另一个高频原因是resources.py是旧版编译的被新版本读取时内存布局不匹配。解决先确认 PyQt5 版本是 5.x不要装 PyQt6。锁定版本执行pip install PyQt55.15.10。然后确认resources.py是从当前resources.qrc编译出来的重编一次pyrcc5 -o libs/resources.py resources.qrc再启动。5.2 图片加载出来是黑的或花的现象图片能打开但显示区域全是黑色或者出现马赛克样式的花屏。原因图片本身没问题通常是 Pillow 的版本问题。新版 Pillow 对某些 JPEG 压缩算法的解码行为有变化特别是使用了 CMYK 色彩空间的 JPEG会被错误解析成 RGBA 然后显示异常。解决把 Pillow 固定在 9.x 系列运行pip install Pillow9.5.0如果项目里其他依赖不允许降级就在labelImg.py里图片加载处加一行强制转换image image.convert(RGB)这行代码的作用是丢弃透明通道和色彩空间元数据强制以 RGB 渲染。5.3 保存的 XML 里中文路径变成乱码现象图片路径包含中文或日文保存的 XML 中path字段显示乱码或整个 XML 无法被解析。原因默认的 XML 写出使用 UTF-8 编码但文件名的编码在被传入QFileDialog时就已经损坏通常发生在 Windows 繁体地区系统或旧版 macOS 文件系统上。解决在启动时强制设置系统编码export PYTHONIOENCODINGutf-8 export QT_LOCALEzh_CN python labelImg.py另外建议图片文件名统一改成英文或数字数据集路径不要放在带有中文的文件夹下。这不是逃避问题后续训练、数据增强、模型部署阶段的工具链对中文路径的兼容性普遍不好早处理早省事。如果你已经有一批乱码 XML可以用一个小脚本批量修复path字段。5.4 画框时坐标偏移对不上图片内容现象鼠标明明画在目标上但松开后框整体偏了若干个像素或者框的尺寸和鼠标拖动的范围不一致。原因显示缩放和坐标映射错位。高 DPI 屏幕上Qt 的窗口坐标逻辑像素和物理像素不一致而labelImg.py在鼠标事件里取的是逻辑坐标画布缩放用的是物理坐标两边一乘就偏了。解决设置环境变量QT_AUTO_SCREEN_SCALE_FACTOR0同时把界面的缩放策略改成固定值不使用系统缩放。还有一个比较隐蔽的坑是外接显示器缩放比例不同主屏 100%、副屏 150%窗口拖到副屏后坐标换算就容易出错建议标注时固定在一个显示器上。5.5 打开目录后图片一张都看不到现象选好目录后图片列表是空的但文件夹里明明有 jpg、png 文件。原因labelImg 默认的文件过滤器只包含常见图片后缀如果你的图片是大写后缀名.JPG或.PNG默认过滤器会忽略掉。解决在文件选择对话框里把过滤器改成*.*或者更彻底一点打开labelImg.py搜self.importDirImages把过滤规则里加一行*.JPG *.PNG *.BMP。改完后重启工具大写后缀的图片就能列出来了。5.6 误删了 XML 想恢复现象标注完一批图后发现 XML 被覆盖或者被误删整个批次作废。解决没有后悔药可以吃这类工具本身没有版本回滚机制。我一般会在动手标注前先把图片目录复制一份做原始备份标注中每隔半小时把 XML 目录压缩一次备份标注完再整体校验一次框数量。这个过程看起来繁琐但比遇到误删后重新标注几个小时要划算得多。6. 把这套工具变成自己团队的生产力工具如果你只是零星标几张图直接用默认配置就够了但如果你是团队里负责搭数据集生产流程的人有很多功能值得优化。一个很容易被人忽略的设置是predefined_classes.txt这个文件定义了左侧类别的预置列表。默认情况下它是空的每次画完一个框都要手动输入类别名效率很低。先花 10 分钟把项目里所有类别写进去cat data/predefined_classes.txt EOF cat dog person car bicycle EOF保存后重新启动 labelImg左侧类别列表会直接显示这些类画框时点击列表中的类别名就能直接赋类不需要再弹输入框。如果用这个配置文件每次启动前确认predefined_classes.txt里是你最新的类别清单因为它的读取时机是启动时运行中修改不会生效。批量校验标注质量时我一般会针对 XML 文件做一个快速检查统计每个文件的标注框数量以及是否有坐标为负值负值通常来自画框时鼠标拖出边界import xml.etree.ElementTree as ET import glob for xml_file in glob.glob(labels/*.xml): tree ET.parse(xml_file) root tree.getroot() for obj in root.findall(object): bndbox obj.find(bndbox) xmin float(bndbox.find(xmin).text) ymin float(bndbox.find(ymin).text) if xmin 0 or ymin 0: print(f{xml_file}: 坐标异常 {xmin},{ymin})这段脚本的排查逻辑很直白读取所有 XML遍历每一个标注框检查最小坐标是否小于零。如果有异常框打开对应图片手动修正。跑一遍只需要几秒但能避免把脏数据喂给训练脚本后整轮训练白跑。把 XML 转成 COCO 格式是另一个高频需求。labelImg 原生只输出 VOC 格式但很多开源代码库用 COCO 的 JSON 注释格式。转换脚本可以复用前面的 XML 解析思路把filename和objects拼装成 COCO 字典结构核心是把所有的 category 建立一个全局 ID 映射再逐图填充 annotations 数组。这个映射必须保证训练、验证、测试三份集共用同一个映射否则评估结果不可信。从那以后我每次给新团队配置标注环境都会强制走一遍「先建虚拟环境、再锁版本、再验证demo图」的流程等到标完几百张图才发现环境不对就太晚了。工具本身不难难的是让生成的数据在训练阶段不反噬。希望这篇笔记能帮你把 labelImg 用顺也帮你在搭数据集的过程里少踩几个坑。本文还有配套的精品资源点击获取