简介：labelImg-master.zip 是开源图像标注工具 labelImg 的源代码压缩包，面向计算机视觉与深度学习开发者、研究人员，用于搭建标注环境，生成目标检测、语义分割等模型所需的像素级标注数据。包内共 123 个文件，以 Python 源码、界面图标、Python 字节码、Shell 辅助脚本及 SVG 矢量资源为主，整体 6.81MB，结构完整清晰，涵盖了主程序源码、UI 资源、配置文件、说明文档、示例图像与许可协议；其中 .py 文件是主程序逻辑，.png 与 .svg 提供界面图标，.pyc 为字节码缓存，.sh 辅助脚本则可用于环境或启动辅助。目前已有 11265 人学习/下载，在同类标注工具中具备较高热度。压缩包内容无缺失、无损坏，解压后即可获得可直接运行的 labelImg 及配套组件，避免从零散渠道收集源码可能带来的文件缺失或版本不匹配问题；内含示例图片和测试数据，便于新用户快速上手标注流程，适合直接应用于实际目标检测与分割项目。
1. LabelImg：图像标注工具中绕不开的实战选择
很多人第一次接触图像标注，是从 labelImg-master.zip 这个压缩包开始的。它不是一个商业级平台，而是一个开源、本地运行、直接启动的图形标注工具，主要用来给图像画矩形框并输出训练所需的标签文件。在实际项目里，不管你是做目标检测的数据准备，还是复现某篇论文的检测流程，LabelImg 几乎是最快能跑通全流程的选项之一。它支持 Pascal VOC 和 YOLO 两种主流输出格式，Windows、Linux、macOS 都能用，对硬件没有要求，一个解压包加 Python 环境就能启动。适合的人群也很清晰：需要快速标注几百到几千张图片的开发者、做课程设计的学生、以及想先跑通目标检测训练链路再决定是否上专业标注平台的团队。
2. 解压与启动：跑通 LabelImg 的完整流程与目录规划
2.1 环境准备与解压位置
资源本身是压缩包，拿到手后第一步是解压。我建议解压到一个路径不含中文、不含空格的目录下，比如D:\tools\labelImg-master。这个细节在 Windows 上尤其重要，因为混合语言路径在某些 Python 版本下会触发编码问题，浪费你半小时排查。
环境方面，LabelImg 依赖 Python 和 PyQt5 绑定。如果你的电脑已经有 Python 3.8 或更高版本，可以只装依赖，不需要额外安装完整 IDE。常见做法是用 pip 安装以下组件：
pip install pyqt5 lxml参数说明：pyqt5是图形界面必须的 Qt 绑定，lxml用来解析和生成 XML 标签文件。如果后续要用到资源包里的部分脚本，可能还需要Pillow。我一般会一次性装齐，避免脚本跑到一半报缺少模块。
2.2 启动图形界面
解压完成后，在对应目录打开命令行，直接运行主程序：
python labelImg.py启动成功后会出现一个包含菜单栏、左侧图片文件列表、中央图像区域、右侧标签列表的界面。如果命令行报错找不到模块，先确认刚才的 pip 安装是否成功，再检查当前命令行所在目录是否确实包含 labelImg.py 文件。
在 macOS 或 Linux 上，如果用的是系统自带 Python，建议先建虚拟环境再安装依赖，避免污染系统环境。Windows 上则不用在意这一点，直接用全局 Python 问题不大。
2.3 打开图片目录与预置标签类别
启动界面后，左侧工具栏中的「Open Dir」按钮是关键入口。点击后会弹出目录选择器，你需要选中存放图片的文件夹。这个工具本身不提供图片管理功能，所以你的图片集要先存在磁盘上。
如果你需要标注的类别是已知且固定的，提前配置类别文件能省很多事。常见做法是在data/predefined_classes.txt里写入所有类别名，每行一个类，不写序号。比如做车辆检测就写person、car、bicycle，做工业质检就写产品缺陷类型。这样在标注时可以直接从下拉列表选择类别，而不是每次弹窗手输，速度提升明显。
有些安装包或源码版本会在启动后自动加载预置类别，如果你的版本没有，可以在工具栏的标签下拉框里手动填写当前类别名。需要注意的是，手动输入的类别名如果带空格或大小写不一致，后续训练时类别映射很容易踩坑。
data/predefined_classes.txt只负责影响标注界面的下拉选项，不会自动修改已有 XML 文件里的类别名。- 修改类别文件后需要重启 LabelImg，或者重新载入图片目录才能生效。
2.4 标注项目的数据目录规划
标注工具的安装只是开始，数据目录规划才是实际项目中真正拉开差距的部分。我经手的模拟项目X中，最初没有规划数据目录，中途才发现图像命名、标注批次全部混在一起，后期转换格式时非常被动。
建议从一开始就固定这样一个结构：
project/ ├── images/ │ ├── batch_001/ │ ├── batch_002/ │ └── batch_003/ ├── annotations/ │ ├── batch_001/ │ ├── batch_002/ │ └── batch_003/ └── classes.txt图像和标注文件按批次一一对应，这样后续划分训练集和验证集时可以直接按 batch 操作，避免同一批次的数据被拆得七零八落。做真实项目时，我一般会要求自己把图片命名规则定为date_sequence.jpg或camera_id_number.jpg，这样即使标注工具不记录额外信息，也能从文件名反查数据来源。
3. 标注界面的五个高频操作：框选、切换、缩放与快捷键
进入标注界面后，你面对的就是一个简洁的图形窗口。学习成本不高，但真正高效使用依赖快捷键，而不是鼠标反复点击。
创建标注框的核心操作是：按住鼠标左键，从目标的左上角拖到右下角，松开后弹出类别输入框，选择或输入类别名，点击确认。每一个框都会在右侧标签列表中显示，对应一个<object>节点。
五个最高频的快捷键是：
W：进入绘制模式，开始画框A/D：切换上一张 / 下一张图片Ctrl + S：保存当前图片的标签文件Ctrl + C：复制当前标注框Delete：删除选中的标注框
当你一张张标注时，建议养成「每完成一张图就按 Ctrl+S」的习惯。LabelImg 不会在切换图片时自动保存，如果标注了几十张没保存，切换后标签文件还是空的。这个坑几乎每个新手都会踩一次。
缩放操作在边缘清晰度要求高的场景下非常关键。使用Ctrl + 滚轮可以放大图像，放大后鼠标拖动画框的精度会显著提升。如果你标注的是密集小目标，例如一排货架上的商品，可以在 View 菜单里切换 Fit Window 模式，但该模式下坐标仍然是原始像素坐标，不会因为缩放而改变。
删除误标注的框也很简单：在右侧标签列表中选中对应项，或者直接在图像上点击框边缘，按 Delete 即可。复制框功能适合连续帧中目标位置和宽高几乎不变的情况，能少画好几次。
4. 避坑指南：LabelImg 实战中的常见问题与排查方法
这一章收录我实际使用中遇到的五个典型问题，每一条都是真实踩过的坑，按「现象 → 原因 → 解决」梳理，方便你遇到时直接对照。
问题一：双击启动后闪退，界面一闪而过
- 现象：运行
python labelImg.py后窗口瞬间消失，没有任何报错。 - 原因：最常见是缺少 PyQt5 图形绑定，或者安装的 PyQt5 版本与 Python 版本不兼容。
- 解决：先确认 PyQt5 已安装，然后在命令行单独执行
python -c "from PyQt5.QtWidgets import QApplication"测试导入是否成功。如果报错，就卸载重装pyqt5。仍然闪退时再检查lxml是否完整。
问题二：打开图片目录后列表为空
- 现象：点击 Open Dir 后左侧文件列表没有出现任何图片。
- 原因：LabelImg 默认过滤图片后缀，如果你的图片格式不在支持列表里，或者文件后缀是大写
.JPG而程序只匹配小写.jpg，就会全部被过滤。 - 解决：手工检查图片后缀是否在
jpg/jpeg/png/bmp范围内，并统一为小写。如果图片本身完整但后缀大小写混用，可以在资源包里看到对应的文件过滤规则，按需修改后重启。
问题三：保存 XML 时报编码错误或路径错误
- 现象：点击 Save 后弹出 Unicode 编码异常，或者提示无法保存到当前路径。
- 原因：Windows 路径中包含中文字符时，lxml 在写文件时默认使用本地编码，可能与程序预期不一致。
- 解决：将整个数据目录迁移到纯英文路径下。如果必须保留中文路径，可以尝试在启动前设置 Python 编码环境变量，但最省事的做法还是路径全英文。
问题四：标注框保存后在图像上的位置偏移
- 现象：保存并重新打开 XML，把标注框叠加回原图时，发现框的位置和保存前不太一样。
- 原因：通常不是工具计算错误，而是操作过程中图像被外部程序修改或替换，导致图像尺寸改变，而 XML 中的坐标仍是旧尺寸下的数值。
- 解决：保存标签后不要再改动原图，尤其是不要压缩、裁剪、旋转后仍沿用原文件名。如果确实需要预处理，先标注后处理，或者处理完再重新标注。
问题五：预置标签不生效，输入类别名总是手输
- 现象：修改了
predefined_classes.txt后，界面上下拉框仍为空。 - 原因：LabelImg 在部分版本中的预置类别加载发生在启动阶段，运行中修改不会热更新。
- 解决：修改类别文件后完全退出程序，再重新启动，并重新打开图片目录。如果还是不行，检查文件是否保存成了 UTF-8 编码，避免 Windows 记事本自动改为带 BOM 的 UTF-8 导致程序读取不到。
5. 从 VOC 标签到训练格式：解析 XML 与生成 YOLO 格式文件
LabelImg 默认保存的是 Pascal VOC 格式的 XML，每张图片对应一个同名 XML 文件。XML 里的核心信息是图像宽高、目标类别、以及每个目标的边界框坐标。但很多训练框架需要的不是 XML，而是 YOLO 格式的 TXT 文件。转换这一步虽然可以用资源包里的工具，但理解转换逻辑能帮你排查不少数据问题。
一个典型的需求是把 XML 转换为 YOLO 格式的 TXT，并确保比例正确：
import xml.etree.ElementTree as ET import os def convert_voc_to_yolo(xml_path, output_dir, class_list): tree = ET.parse(xml_path) root = tree.getroot() size = root.find('size') image_width = int(size.find('width').text) image_height = int(size.find('height').text) lines = [] for obj in root.findall('object'): name = obj.find('name').text if name not in class_list: continue class_id = class_list.index(name) bndbox = obj.find('bndbox') xmin = float(bndbox.find('xmin').text) ymin = float(bndbox.find('ymin').text) xmax = float(bndbox.find('xmax').text) ymax = float(bndbox.find('ymax').text) x_center = (xmin + xmax) / 2.0 / image_width y_center = (ymin + ymax) / 2.0 / image_height box_width = (xmax - xmin) / image_width box_height = (ymax - ymin) / image_height lines.append(f"{class_id} {x_center:.6f} {y_center:.6f} {box_width:.6f} {box_height:.6f}") xml_name = os.path.splitext(os.path.basename(xml_path))[0] output_txt = os.path.join(output_dir, xml_name + '.txt') with open(output_txt, 'w') as f: f.write('\n'.join(lines))这段代码的逻辑是：读取 XML 中的真实图像宽高，把每个目标的左上角和右下角坐标换算成中心点坐标与宽高，再全部除以图像宽高得到 0～1 之间的比例值。class_list的顺序就是训练时类别 ID 的映射顺序，顺序变化会改变所有标注的类别编号，务必和训练配置保持一致。
如果你标注的是带有难以界定的边缘物体，例如阴影边缘、遮挡部分，你会希望坐标值越精确越好，这时候手动微调坐标的实际操作依然发生在标注界面内。XML 转换脚本只解决格式问题，不解决框不准的问题。
6. 用效率习惯固化标注流程：复盘一个逐步优化的技巧
最后一个技巧来自我实际标注 5000 张图片后的习惯复盘。第一次做标注任务时，我边标边想怎么加速，后来总结出一套固定动作，全套走下来比闷头框选快不少。
第一，先把预置类别文件写好。这听起来简单，但很多人会跳过，导致每个框都手输一遍类别名。类别文件每行一个类，顺序就是类别 ID 顺序，我一般会在开始标注前重新核对一遍，确认没有多余空行。
第二，设置图像文件列表的显示排序。LabelImg 默认按文件名排序，如果你的批次文件是按拍摄时序命名的，这正好能帮你按场景连续标注。我习惯把同批次、同光照条件的图放在一个目录下，按顺序标注，避免反复切换标注逻辑。
第三，批量标注同类目标时频繁用复制框。连续帧里目标位置变化不大时，选择已有框并按 Ctrl+C，然后在新图片上粘贴，再微调位置，比重新画一遍快两倍以上。复制框的快捷键在资源包的源代码里有明确绑定，不同版本可能不同，在你的版本里查一下对应动作即可。
第四，定期清理存档文件。标注过程会产生大量 XML，我一般每标完一个批次就做一次目录快照，把 XML 和对应图片一起压缩归档，避免后期误删、覆盖造成标签丢失。归档本身不增加额外工作，但能防止最长见的翻车事故。
第五，用验证脚本做前后一致性检查。写一个简短检查脚本统计 XML 里标注框数量、类别分布，以及是否与图片文件名一一对应。这类脚本在资源包里有时会附带，没有也可以自己写，逻辑不复杂但价值很高。
标注工具的价值不完全在于它本身的功能列表，而在于你能用稳定、可复现的流程把一批图像转换成可训练的数据。从那以后，我每次开始新的标注任务都会强制走一遍：先配类别文件，再按逻辑分目录，接着定快捷键习惯，最后每批量做一次归档和一致性检查。整套流程练熟后，标注速度和个人状态关系不大，更多是流程在驱动进度。希望帮到你。
本文还有配套的精品资源，点击获取
