简介LabelImg-master.zip 是一款面向计算机视觉与神经网络训练场景的开源图像标注工具源码包适合从事目标检测、语义分割等深度学习任务的研究者、算法工程师及数据标注人员使用可解决训练数据集制作中标注效率低、格式不统一的问题。压缩包共108个文件约6.29MB以27个py源码文件为核心辅以39个png界面图标、6个svg矢量图、6个sh脚本及rst、md说明文档另含properties、yml等配置与少量示例图片结构完整便于二次开发。目前已有425人学习下载。资源提供直观GUI支持矩形框、多边形等多种标注类型标注结果可保存为XML或JSON格式并支持加载续编兼容Windows、Mac OS与Linux还支持自定义快捷键提升效率随附安装说明与常见错误解决思路帮助读者快速搭建Python环境、安装依赖并启动程序从而高效构建高质量训练数据集。1. 图片标注工具里的老黄牛labelImg 到底还值不值得用如果你正在做目标检测手头攒了几千张图却还没标几个框那大概率会被人安利过 labelImg。它是个用 Python Qt 写的桌面端图片标注工具核心功能就一件事在图上拉框、打标签、导出成 PASCAL VOC 的 XML 或 YOLO 的 TXT。听起来朴素但它解决的是神经网络项目里最枯燥也最要命的一环——把原始图片变成模型能吃的标注数据。labelImg-master.zip 就是它的源码包解压即用不依赖在线服务不挑显卡一台普通办公本就能跑。适合谁刚入门目标检测、需要快速把一批图变成训练集的人也适合那些不想被在线标注平台按张收费、想把数据留在本地的团队。下面我按实际拆包、跑通、踩坑的顺序把这份资源讲透。2. 拆开 labelImg-master.zip目录结构、依赖与启动方式拿到压缩包先别急着双击解压后你会看到一个典型的 Python 项目目录。理解它每个文件夹干什么后面改配置、排错才不会抓瞎。2.1 源码目录里有什么解压 labelImg-master.zip 后根目录下主要包含这些内容路径作用labelImg.py主程序入口双击或命令行运行它libs/核心逻辑画框、读写标注、画布交互都在这里resources/图标、样式等静态资源data/预定义的类别文件比如predefined_classes.txtrequirements/分版本的依赖清单按系统选build-tools/打包相关脚本普通使用用不到README.md官方说明但版本更新后有些步骤会过时真正要关心的只有labelImg.py、libs/和data/predefined_classes.txt。前者是入口中间是逻辑后者是你自定义类别的落脚点。2.2 依赖安装别直接 pip install 一堆很多人翻车在第一步直接pip install labelImg或者照着旧教程装一堆包结果 Qt 版本冲突窗口起不来。正确做法是先看requirements/下对应你系统的文件。以 Linux 为例常见做法是# 进入解压后的目录 cd labelImg-master # 根据系统选择依赖文件Linux 通常用这个 pip install -r requirements/requirements-linux-python3.txt # 如果上面文件不存在用通用版 pip install -r requirements/requirements.txt逻辑说明requirements-linux-python3.txt里锁定了PyQt5和lxml的版本区间避免装到不兼容的新版。参数上如果你用 Python 3.9 以上建议先建虚拟环境再装否则系统里已有的 PyQt 可能把新装的覆盖掉。装完用python labelImg.py启动能弹出窗口就说明依赖通了。2.3 启动与界面速览启动命令很简单python labelImg.py窗口出来后左侧是文件列表中间是画布右侧是标签列表和几个按钮。关键操作就几个快捷键W画框D下一张A上一张CtrlS保存。第一次用建议先点左侧「Open Dir」选图片文件夹再点「Change Save Dir」选标注保存位置然后点「Create RectBox」开始拉框。这里有个细节保存格式默认是 PASCAL VOC 的 XML如果你要喂给 YOLO得在菜单里切换成 YOLO 格式否则后面还得写脚本转多一道手续。3. 把标注流程跑通从单张图到批量导出 YOLO 格式工具能启动只是第一步真正要落地的是「标完一批图导出成训练脚本能直接读的格式」。这一章把完整链路走一遍。3.1 预定义类别与快捷键配置在data/predefined_classes.txt里一行写一个类别名比如person car dog保存后重启 labelImg右侧标签列表就会预加载这些类别。这样标注时直接点选不用每次手打减少拼写不一致导致的训练报错。如果你类别多建议按字母序排找起来快。另外菜单里可以开启「Auto Save Mode」每切一张图自动保存适合大批量标注时防止手滑丢进度。3.2 标注操作与 XML 结构画一个框后labelImg 会在你指定的保存目录生成同名 XML。以一张frame_001.jpg为例生成的frame_001.xml结构如下annotation folderimages/folder filenameframe_001.jpg/filename size width1920/width height1080/height depth3/depth /size object nameperson/name bndbox xmin320/xmin ymin210/ymin xmax480/xmax ymax560/ymax /bndbox /object /annotation逻辑说明size记录原图宽高bndbox是左上角和右下角坐标单位是像素。注意xmax和ymax是框的右下角不是宽高写转换脚本时别搞反。参数上如果图片被旋转过labelImg 不会自动校正标注前最好把图统一摆正。3.3 导出 YOLO 格式与坐标归一化YOLO 要的 TXT 每行是类别索引 x_center y_center width height且全部归一化到 0~1。labelImg 菜单里可以直接切换保存格式为 YOLO切换后新保存的标注就是 TXT。但如果你已经标了一批 XML 才想起来要转可以用下面这个脚本批量转import os import xml.etree.ElementTree as ET # 类别列表顺序必须和训练时的 data.yaml 一致 classes [person, car, dog] def convert(xml_dir, txt_dir, img_w, img_h): for xml_file in os.listdir(xml_dir): if not xml_file.endswith(.xml): continue tree ET.parse(os.path.join(xml_dir, xml_file)) root tree.getroot() lines [] for obj in root.iter(object): cls_name obj.find(name).text if cls_name not in classes: continue cls_id classes.index(cls_name) bnd obj.find(bndbox) xmin float(bnd.find(xmin).text) ymin float(bnd.find(ymin).text) xmax float(bnd.find(xmax).text) ymax float(bnd.find(ymax).text) # 归一化并转中心点格式 x_center (xmin xmax) / 2.0 / img_w y_center (ymin ymax) / 2.0 / img_h w (xmax - xmin) / img_w h (ymax - ymin) / img_h lines.append(f{cls_id} {x_center:.6f} {y_center:.6f} {w:.6f} {h:.6f}) txt_name xml_file.replace(.xml, .txt) with open(os.path.join(txt_dir, txt_name), w) as f: f.write(\n.join(lines)) # 调用时传入实际图片宽高如果尺寸不一需要逐张读取 convert(annotations_xml, labels_txt, 1920, 1080)逻辑说明脚本遍历 XML把每个 object 的坐标按图片宽高归一化再转成中心点加宽高的格式。参数上classes列表的顺序必须和训练配置里的names完全一致否则类别索引错位模型学出来的东西全乱。如果图片尺寸不统一得用 PIL 或 OpenCV 逐张读实际宽高不能写死。3.4 批量校验标注质量标完几千张难免有漏标或框歪的。跑训练前建议做一次快速校验统计每张图的框数量、检查有没有宽高为 0 的框、确认类别名没有拼错。常见做法是写个脚本扫一遍 TXT把异常文件名打印出来人工复核。这一步花十分钟能省掉训练几小时后发现 loss 不降的后悔药。4. 避坑与排查labelImg 用起来最容易翻车的五个地方这工具本身不复杂但环境、格式、操作习惯上的坑不少。下面五条是我和身边人实际踩过的按「现象 → 原因 → 解决」写清楚。4.1 启动报错 Qt platform plugin 找不到现象命令行运行python labelImg.py报qt.qpa.plugin: Could not load the Qt platform plugin xcb窗口不弹。 原因PyQt5 装上了但系统缺少 xcb 相关的底层库常见于精简版 Linux 或没装图形依赖的容器环境。 解决补装系统库Debian 系用sudo apt install libxcb-xinerama0 libxcb-cursor0然后重新运行。如果还不行检查QT_QPA_PLATFORM_PLUGIN_PATH环境变量是否指向了正确的 PyQt5 plugins 目录。4.2 标注保存后 XML 里没有 object现象明明画了框保存后打开 XML 发现object是空的。 原因画框后没有在弹出的小窗里输入或选择类别名直接点了 OK 或按了回车labelImg 认为这个框无效。 解决画框后必须给标签可以从右侧列表点选也可以手动输入。开启 Auto Save 前先确认这个习惯已经养成。4.3 图片路径含中文导致读取失败现象Open Dir 选了文件夹左侧列表空白或者图片显示为裂图。 原因labelImg 底层用 Qt 读文件部分版本对中文路径支持不好尤其是 Windows 下。 解决把图片和标注目录都改成纯英文路径比如D:/dataset/images。这是最省事的办法别跟编码较劲。4.4 YOLO 格式导出后训练报类别越界现象训练时提示IndexError: list index out of range或类别索引对不上。 原因labelImg 导出 YOLO 时用的类别顺序和你在data.yaml里写的names顺序不一致。 解决统一以predefined_classes.txt的顺序为准导出前确认菜单里的类别列表和训练配置完全一致。转换脚本里的classes也要同步。4.5 大图标注卡顿现象标注 4K 以上图片时画布拖动明显延迟画框跟不上鼠标。 原因labelImg 默认会把原图缩放到画布显示图越大Qt 渲染开销越高。 解决标注前先把图片统一缩到 1920 宽以内或者换用更轻量的标注工具处理超大图。如果必须保留原图标注时关掉「Fit Window」以外的预览选项减少重绘。5. 进阶技巧用脚本把标注、校验、转换串成一条流水线单张标、手动转图少还行上千张就是体力活。我后来习惯把 labelImg 当成纯标注端后面的校验和格式转换全部脚本化形成一条固定流水线。5.1 标注前先统一图片尺寸和命名在打开 labelImg 之前先跑一个预处理脚本把所有图片缩到统一宽度并按类别_序号.jpg重命名。这样标注时不用来回缩放转换时宽高也能直接用固定值省掉逐张读图的步骤。常见做法是用 OpenCV 批量 resizeimport cv2 import os src_dir raw_images dst_dir images target_w 1280 os.makedirs(dst_dir, exist_okTrue) for idx, name in enumerate(sorted(os.listdir(src_dir))): img cv2.imread(os.path.join(src_dir, name)) if img is None: continue h, w img.shape[:2] scale target_w / w new_h int(h * scale) resized cv2.resize(img, (target_w, new_h)) cv2.imwrite(os.path.join(dst_dir, fimg_{idx:05d}.jpg), resized)逻辑说明统一宽度后高度按比例缩放避免拉伸变形。参数target_w根据你的显存和模型输入来定一般 1280 够用。命名用零填充序号保证文件列表顺序稳定。5.2 标注后自动校验并生成训练配置标完一批跑一个校验脚本检查每个 TXT 的坐标是否在 0~1 之间、类别索引是否越界、有没有空文件。校验通过后自动生成 YOLO 训练用的data.yamlimport os labels_dir labels_txt classes [person, car, dog] # 校验 bad_files [] for name in os.listdir(labels_dir): path os.path.join(labels_dir, name) with open(path) as f: for line in f: parts line.strip().split() if len(parts) ! 5: bad_files.append(name) break cls_id int(parts[0]) coords [float(x) for x in parts[1:]] if cls_id len(classes) or any(c 0 or c 1 for c in coords): bad_files.append(name) break print(异常文件, bad_files) # 生成 data.yaml with open(data.yaml, w) as f: f.write(ftrain: ./images\n) f.write(fval: ./images\n) f.write(fnc: {len(classes)}\n) f.write(fnames: {classes}\n)逻辑说明校验部分逐行检查字段数和数值范围把有问题的文件名收集起来人工复核。生成配置时nc是类别数names顺序必须和标注时一致。参数上train和val路径按你的实际目录结构改小数据集可以暂时用同一份。5.3 版本管理标注文件也要进 Git标注数据是模型迭代的核心资产但很多人只备份图片忘了 XML/TXT。我一般把标注目录单独做一个 Git 仓库每次标完一批就 commit 一次commit message 写清楚标了多少张、改了哪些类别。这样后面模型效果波动时能回溯到具体是哪批标注引入的问题。注意图片本身太大用.gitignore排除只跟踪标注文件。从那以后我每次开新项目都强制走一遍「预处理 → 标注 → 校验 → 生成配置」这条流水线不再手动一张张转格式。希望帮到你。本文还有配套的精品资源点击获取