简介labelImg 是一款广泛使用的开源图像标注工具这份 master 分支源码压缩包面向计算机视觉与深度学习研究者提供完整的图形化标注界面可高效创建目标检测、语义分割所需的像素级标注数据。包体整体为 6.81MB共 123 个文件核心为 28 个 Python 源文件如 labelImg.py 主程序辅以 39 个 png 图标资源、6 个 shell 脚本、3 个 rst 文档以及 README、LICENSE 等文件结构清晰解压后即可按文档配置依赖并运行。目前已有 11218 人学习或下载是入门与进阶物体检测项目常用的工具之一。资源附带完整的代码、界面资源、示例文件与使用说明可帮助用户快速搭建标注环境将标注成果直接用于 Faster R-CNN、YOLO 等模型的训练流程省去自行整理环境的麻烦。 做目标检测的朋友应该都绕不过 dataset 制作这道坎。早些年我还在用画图软件手工拉框存坐标的时候第一次碰到 labelImg 这个工具瞬间觉得之前全是在用蛮力。一直到今天labelImg-master.zip这个包还在我网盘里躺着换电脑第一件事就是把它解压出来跑一遍。这篇就把我从下载安装到实际标注再到踩坑排错的全过程拆开讲明白尤其是不少新手都在问的“正方形框不生效”和“标注中闪退”一并说清楚。1. labelImg 到底是什么为什么至今仍是入门首选labelImg 是一款基于 Python PyQt5 开发的图形化图像标注工具主要用来画目标检测所需的边界框也就是 Bounding Box。它做的事情非常纯粹你打开一张图片用鼠标框出目标填一个类别名称然后保存成模型训练能读的文件格式。官方源码打包成的labelImg-master.zip就是我们要下载的核心内容解压后直接运行脚本即可不需要复杂的安装流程。这个工具支持两种在目标检测领域最主流的标注格式PascalVOC 的 XML 文件以及 YOLO 的 TXT 文件。前者在物体检测大赛和传统检测算法里极其常见后者则是 YOLO 系列模型直接消费的标签格式每行五个数字类别序号加归一化后的中心点坐标和宽高。简单来说labelImg 解决了“把像素位置变成模型能读的数字”这一最原始刚需。从 2015 年项目发布到现在市面上出现了不少更花哨的标注工具比如 labelme 主攻多边形实例分割CVAT 支持多人协同加 AI 预标注X-AnyLabeling 甚至能抵押深度学习模型做半自动标注。但 labelImg 依然有自己的位置安装零门槛、界面极其轻量、单机标注不依赖服务端、训练小规模自定义数据集完全够用。我见过不少教学项目、实验室课题和竞赛 Demo 都在用它原因无他——省事、够用、团队同学都能快速上手。2. 从 labelImg-master.zip 开始环境准备与安装全流程2.1 为什么不建议直接 pip install labelImg很多初学者上来就敲pip install labelImg装完启动时报错或者打不开界面然后跑来问是怎么回事。我吃过这个亏所以先把原因说透PyPI 上维护的 labelImg 版本通常落后源码仓库版本不少而且它不会自动帮你把 PyQt5 和 lxml 的兼容关系理顺。尤其到了 Python 3.10 之后的版本老版本的 PyQt5 绑定很容易出问题。正确的做法是直接从 GitHub 仓库下载labelImg-master.zip源码压缩包解压后手动安装依赖再用 Python 启动主程序。这样你能确保拿到的是最新功能和修复出了问题也方便直接看源码排查。2.2 Windows 平台完整安装步骤在 Windows 上操作其实非常简单我把完整流程写在这里你照着复制就能跑起来。首先确保你本机已经装了 Python 3.8 到 3.10 之间的版本。实测下来 3.10 以下兼容性最稳Python 3.11 或 3.12 在某些 PyQt5 版本上会出现Qt Platform Plugin这类初始化崩溃。接下来解压labelImg-master.zip到你想要的位置。这里有一条重要的经验整个解压路径不要包含中文、空格和特殊字符。我之前图省事放在D:\标注工具\labelImg-master下启动时直接闪退改成D:\labelImg-master后就再也没有问题了。然后在当前目录打开命令行终端依次执行pip install PyQt5 lxml python labelImg.py如果一切顺利一个灰色背景的标注窗口就会弹出来。但如果你用的是新版 Python或者系统里有多个 Python 环境也可以先创建一个干净环境再装python -m venv labelimg-env labelimg-env\Scripts\activate pip install PyQt5 lxml python labelImg.py2.3 macOS 和 Linux 的补充说明macOS 用户可以直接用 Homebrew 安装 Qt 库brew install qt brew install python3.9 pip install PyQt5 lxml然后在源码目录下运行python labelImg.pyLinux 用户如果是 Ubuntu 系可以安装系统级依赖sudo apt-get install pyqt5-dev-tools python3-lxml依赖装好之后在源码目录下直接启动即可。Linux 下比较容易出现的问题是高分辨率屏幕下界面显示过小可以用环境变量临时指定缩放export QT_AUTO_SCREEN_SCALE_FACTOR1 python labelImg.py3. 标注实操全解析从打开一张图到导出数据集3.1 界面布局和核心区域真正进入标注界面之后你会看到几个关键区域左侧工具栏存放打开目录、打开文件、保存、画框、删除框等核心按钮中间画布区显示当前待标注的图片支持缩放和拖拽右侧文件列表显示当前文件夹下所有图片方便快速切换底部标签栏显示已经标注的框的类别和坐标信息第一次打开 labelImg 的人往往会忽略一个核心细节默认格式是 PascalVOC也就是保存时会生成 XML 文件。如果你想使用 YOLO 训练必须提前切换到 YOLO 模式。在界面上部或者邮件菜单中能找到格式切换的选项具体做法是点击菜单栏的 “PascalVOC” 按钮从下拉列表里选中 “YOLO”。3.2 一个完整的标注流程我把一次完整的标注流程拆解出来照着这个顺序做可以避免重复劳动。第一步点击左侧 “Open Dir” 按钮选择存放图片的文件夹。注意这个文件夹里最好只放图片不要混入其他格式的文件否则右侧文件列表会显得很乱。第二步点击 “Change Save Dir” 按钮选择保存标签文件的输出目录。如果不设置标签文件会和图片放在一起。第三步使用快捷键 W进入画框模式。此时鼠标在图片上变成一个十字准星按住左键拖动松开后会自动弹出标签输入框录入类别名称。第四步确认标签无误后点击 OK你会在左侧底部和画布上看到这个标注框。如果框的位置或大小不对直接用鼠标点击选中然后拖动边缘调整。不满意就按下快捷键 CtrlY 删除当前选中的框重新绘制。第五步按 CtrlS 保存当前图片的标注文件然后按 D 键或者点击右键选择 “Next Image” 切换到下一张图片。整个过程非常机械化熟练之后一张图只需要十几秒。3.3 快捷键对照表建议收藏我用熟练之后基本全程不碰鼠标按钮效率高很多。下面是常用的快捷键整理功能快捷键说明画边界框W进入绘制模式拖动鼠标画框删除选中框CtrlY删除当前选中的标注框保存标注CtrlS生成 XML 或 TXT 文件下一张图D切换到下一张图片上一张图A切换到上一张图片放大画布Ctrl滚轮局部细节标注时非常常用拖动画布空格左键拖动放大后可用编辑框的标签CtrlE重新输入类别名称搜索图片CtrlF按文件名快速跳转注意如果你的系统输入法把快捷键拦截了尤其是 W 和 A、D 键请先切换到英文输入法再操作。国产输入法在中文状态下经常会吃掉这些快捷键导致画不了框、切不了图误以为是软件故障。4. 高频故障排查实录正方形框不生效与闪退4.1 “切换正方形框不生效”到底是怎么回事这个问题在热搜里排得很靠前说明遇到的人很多。先说结论labelImg 默认画的是自由矩形你要画正方形需要按住 Shift 键再拖动鼠标。很多用户不知道这个设计始终用普通单击拖拽的方式自然画不出正方形。但如果你按住 Shift 键还是不生效我根据实操经验总结了三个排查方向。第一个方向是输入法抢占。Windows 上最典型的就是搜狗、微软拼音等输入法中英文切换快捷键默认是 Shift 键。当你在画框时按住 Shift实际上触发了输入法切换软件根本没收到这个按键事件。解决办法是把输入法的切换快捷键改成 CtrlSpace或者干脆临时切到英文输入法再标注。第二个方向是菜单设置被误改。labelImg 菜单栏有一个 “Edit” 菜单里面有一项 “Keep Square” 选项勾选之后所有绘制的框都会被强制限制为正方形。如果你此前勾选过现在画出的只会是正方形自由矩形无法绘制你会误以为是“正方形特效失效”的反向问题。取消勾选后使用 Shift 才会恢复正常。第三个方向是版本太老。部分旧版本对 Shift拖动 的支持存在 Bug尤其是在某些 Linux 桌面环境下。如果你用的是很老的 release 包建议重新下载最新的labelImg-master.zip界面标题栏上会显示版本号建议至少 1.8.0 以上。4.2 启动闪退或标注中途闪退的原因和处理闪退是另外一个高频搜索词遇到的人心态通常比较崩。我分析一下最常见的原因和修复手段。闪退原因第一名是 PyQt5 依赖版本不兼容。这种情况多出现在 Python 3.11 及以上版本老版本 PyQt5 在加载插件时进程直接被系统杀死连报错弹窗都没有。解决办法是先把 PyQt5 固定到 5.15.4 或 5.15.7这是实测中比较稳定的版本段pip uninstall PyQt5 pip install PyQt55.15.7第二个常见原因是路径中包含中文或特殊字符。解压路径、图片路径、保存标注的路径这三者任何一个带中文都可能导致底层 Qt 组件在读取文件时抛异常闪退。这是一个很多人忽略的细节把文件全部转移到纯英文路径下能解决大部分闪退。第三个原因是图片本身有异常。比如某些图片文件扩展名是 .jpg但实际编码格式是 WebP 或 Crop 损坏格式Qt 的 QImageReader 组件解析时出现内存越界程序直接退出。遇到这种情况建议先把整个图片文件夹做一次统一转换用 Python 脚本批量转成标准 RGB JPEGfrom PIL import Image import os folder path/to/your/images for fname in os.listdir(folder): if fname.lower().endswith((.jpg, .jpeg, .png)): path os.path.join(folder, fname) try: img Image.open(path) img img.convert(RGB) img.save(path, JPEG, quality95) except Exception: os.remove(path)这个暴力清洗方案在数据量几百张时非常管用。4.3 其他高频小毛病除了上面两个大问题还有几个小毛病也值得记一笔。一个是打开软件后界面空白画布区域什么都显示不出来。这种情况多由显卡驱动或者 Qt 渲染后端异常引起在 Windows 上临时设置环境变量可以绕过set QT_OPENGLsoftware python labelImg.py另一个是保存标签时提示无权限。如果你把输出目录设在 C 盘 Program Files 这类受保护目录下普通用户没有写入权限。把输出目录换到自定义的文件目录即可。还有一个是输入标签时中文乱码。这通常不是工具的问题而是数据集训练时编码格式不匹配。labelImg 保存的 XML 默认使用 UTF-8 编码TXT 则普通文本如果你的后续处理代码默认用 GBK 读取就会出现乱码。建议所有脚本统一用encodingutf-8读取标签文件。5. 标签数据的高级整理技巧与效率提升心得5.1 类别管理要提前规划别等标完再后悔很多人标注时会随手录入类别名比如先写 “cat”下一张又写成 “Cat”最后训练时发现两个类同名不同写白白增加数据清洗时间。我的习惯是标注开始之前先确定一个类别清单并把每个类别的拼写和大小写固定住。可以在 labelImg 的data/predefined_classes.txt文件里预定义类别列表这样在标注画框时点击右侧下拉框就能直接选择已有类别不需要每次手动输入极大提高效率也避免拼写错误。5.2 善用自动保存减轻重复劳动很多新用户不知道 labelImg 自带自动保存功能。在菜单栏 “Edit” 下面是 “Auto Save Mode”勾选之后每当你切换到下一张图片时当前图片的标注文件会自动保存不用再手动按 CtrlS。这在连续标注时非常舒服手不用反复离开鼠标。唯一需要注意的是自动保存对已经画了框但还没输入类目的半成品也会保存容易产生空标签文件所以切图前养成先确认备注的习惯。5.3 批量检查和校验标签内容标注完几百张图片后逐手打开检查效率极低。我一般直接写脚本扫描所有 XML 文件检查是否有缺失文件、标签类别是否超出预设集合、坐标是否越界。一个简单的检查逻辑可以这样写import os import xml.etree.ElementTree as ET xml_dir path/to/Annotations valid_classes {cat, dog, car} for fname in os.listdir(xml_dir): if not fname.endswith(.xml): continue tree ET.parse(os.path.join(xml_dir, fname)) root tree.getroot() for obj in root.findall(object): cls obj.find(name).text bbox obj.find(bndbox) xmin int(bbox.find(xmin).text) ymin int(bbox.find(ymin).text) xmax int(bbox.find(xmax).text) ymax int(bbox.find(ymax).text) if cls not in valid_classes: print(f{fname}: unknown class {cls}) if xmin xmax or ymin ymax: print(f{fname}: invalid bbox)同样道理如果你用的是 YOLO 格式可以检查每一行是否包含五列数字类别编号是否在合法范围内坐标值是否都在 0 到 1 之间。这样的静态检查能在训练前拦截超过八成的格式错误。5.4 从 labelImg 走向半自动标注的小建议标注永远是目标检测项目里最费时间的一环。如果你手头的数据量大到几千张纯靠 labelImg 手工拉框显然不现实。我的做法是先用手工标注一小部分数据比如每个类别 50 张训练一个粗版检测模型然后对剩余图片做预测生成预测框之后再用 labelImg 打开修正。虽然 labelImg 没有内置的预标注加载功能但你可以用 Python 脚本把模型的预测结果转换成 PascalVOC 格式的 XML 文件直接在 labelImg 中打开调整。这样整体标注效率提升数倍适合有一定 Python 基础的研究者尝试。写在最后的几个心得回过头来看labelImg 是那种“用起来觉得朴素但离不开”的工具。我踩过不少坑尤其是升级 Python 后闪退、路径带中文出问题这些排查经验现在都沉淀成了固定的工作习惯。如果你和我一样是动手派建议把labelImg-master.zip解压后放在一个固定目录配合一个干净的虚拟环境然后花 10 分钟把快捷键和自动保存模式调好后面整个标注流程会舒服很多。这工具虽然更新频率不高但在小型自定义数据集这条场景线上它依然是最顺手的那把刀。本文还有配套的精品资源点击获取