简介LabelImg目标检测标注工具的安装与使用教程PDF面向目标检测领域的研究者、开发者和课程学员帮助零基础用户快速掌握该工具的安装与标注操作。资源为单个PDF文档约1.71MB内容紧凑涵盖在Windows环境下通过pip命令并借助清华镜像源安装LabelImg、启动后的界面初始化设置、在View菜单中勾选自动保存模式、指定图片文件夹与标注文件保存目录等完整流程。教程重点介绍了W/D等快捷键的用法可显著提升标注效率同时分别展示了PASCAL VOC与YOLO两种标注格式的输出结果对XML文件中的图像尺寸、通道数、标签名称及边界框参数进行了解读并说明YOLO格式中归一化中心点坐标、目标框宽高的含义及classes.txt文件的创建方法。此外还提示了labelimg.exe通常安装在Python的Scripts目录下可通过Everything工具快速查找便于用户定位可执行文件。此PDF目前已有2420人学习下载适合作为目标检测数据预处理的入门参考。1. LabelImg 这个老牌标注工具为什么到现在还在被推荐如果你要从零开始做一个目标检测项目第一件绕不开的事就是给图片画框。YOLO 系列教程里动不动就出现一个界面简洁、画框迅速的小工具这就是 LabelImg。我自己最初入坑检测方向时用的第一个标注工具就是它而不是市面上那些在线平台。原因很简单它在本地运行标注数据不外传而且标注完的文件格式是标准的 Pascal VOC 或 YOLO txt几乎能直接喂给训练脚本省掉一大段格式转换的时间。这篇文章会把安装、界面操作、格式切换、标注步骤和实际踩过的坑一次性说清楚。对刚接触目标检测的同学来说照着做就能在半小时内进入标注状态对已经用过一段时间的老手来说资源和标注文件的组织习惯、路径坑、版本匹配问题或许能帮你省一次重装的功夫。2. 它解决的是什么问题从图片到可训练数据集的关键一环2.1 标注工具在检测流程里的位置目标检测训练需要先回答“物体在哪、是什么”这两个问题。算法本身不会直接看懂一张普通图片它依赖标注数据去学习目标的边界框坐标和类别。LabelImg 承担的就是把人工视觉判断转成机器可读坐标文件这一步。常见做法是采集或下载一批图片后用 LabelImg 打开文件夹逐张在目标周围画矩形框并为每个框指定类别。完成后工具会把坐标信息写入一个与图片同名的文件——Pascal VOC 模式下生成 XMLYOLO 模式下生成 TXT。训练脚本读取这些文件后才能把“第几张图、哪个位置、属于什么类”的信息和图片像素关联起来。这个工具的定位不是复杂的版本管理或多人协作而是单机完成标注的轻量场景。你不需要部署服务端、不需要申请账号、不需要考虑数据库配置装好就能用。对于个人项目、课程设计和几万张以内的小规模数据集它的性价比是最高的。2.2 为什么还用老工具而不是直接用现代标注平台现在确实有越来越多功能丰富的标注工具比如自动分割、标签推荐、云端协同等。但选型要看场景数据敏感性如果你做的是学校课题或者公司内部项目图片不方便上传到第三方平台本地工具更稳妥。格式兼容便捷性LabelImg 生成的文件结构与目标检测任务中常见的 YOLO 训练格式几乎是标准化的。而很多平台导出时还要再经过一次格式转换增加出错的概率。硬件门槛它只需要一台能跑 PyQt 的普通电脑不需要 GPU也不需要特别高的配置。教室里的老旧台式机同样能跑。我做课程设计时常用的组合是 LabelImg 做标注 一份 YOLO 训练代码。标注完成后把图片和 txt 文件按目录整理好直接就能开始训练中间不需要写额外的转换脚本。这种“即标即用”的体验让我一直舍不得换成更重的方案。3. 安装的三种路径pip、源码编译与免安装 exe安装这一步对新手来说是最容易卡住的。因为 LabelImg 的官方文档主要面向 LinuxWindows 用户如果直接照搬命令很可能会在安装 PyQt5 或编译资源时翻车。下面把三种常见方式都列出来按你的操作系统选一种就行。3.1 路径一pip 安装Python 环境已经齐全时最省事如果你的电脑上已经配置好了 Python 3.9 及以下版本pip 安装是最快的路径。打开命令行执行pip install labelImg执行完之后直接在命令行输入labelImg按回车标注界面就会弹出来。参数说明这里的labelImg是安装后的命令行入口不是文件名也不是项目目录。pip 会自动拉取 PyQt5 和 lxml 等依赖一般不需要手动安装。这是最简单的方法但要提醒一句我实际使用中遇到最多的问题是 Python 3.10 及以上版本和这个工具不对付启动时经常报版本兼容错误。下面 3.3 会给到替代方案。3.2 路径二从 GitHub 克隆源码自行运行适合需要看内部逻辑的同学如果你后续想改 UI 或者给工具添加自定义快捷键建议走源码运行方式。git clone https://github.com/HumanSignal/labelImg.git cd labelImg pip install pyqt5 lxml pyrcc5 -o libs/resources.py resources.qrc python labelImg.py说明一下这几条命令的作用克隆项目到当前目录后进入项目根目录。安装两个核心依赖pyqt5 提供图形界面lxml 用来解析和生成 XML 文件。编译资源文件让程序能加载界面图标和样式——这一步不能跳过否则打开程序会提示缺少图标或直接白屏。最后用 Python 运行主程序。这里有个编译环境的问题pyrcc5是 PyQt5 自带的资源编译器如果你安装的是 PyQt5 但没有把工具目录加入系统环境变量会提示命令找不到。这时候可以找到 Python 安装目录下的Scripts文件夹把路径手动加到系统变量里。3.3 路径三下载 Windows 免安装版新手最稳的方案如果你不想折腾 Python 环境直接下载打包好的免安装压缩包是最省心的选择。操作步骤在 GitHub 的 Release 页面下载windows-vX.X.zip版本。解压到任意目录双击labelImg.exe。软件启动后界面为英文功能与源码版一致。我没有去核对具体版本号因为这类发布包更新不是那么频繁你只需要认准官方仓库 Releases 页面最近发布的那一版就行。这部分有一个值得留意的细节Windows 上建议把解压后的目录放在纯英文路径下比如D:\tools\labelImg。放在“桌面”或含中文名的文件夹里后续某些操作会莫名出问题最常见的是打开图片目录时软件没有任何反应或保存时弹窗报错。具体原因在避坑章节会展开。3.4 安装完成后第一次启动快速验证装好之后不要急着画框。先做一次基础验证确认环境没问题再进入正式标注流程。labelImg如果界面成功弹出说明安装成功。如果报错优先检查 Python 版本是否过高或者 PyQt5 是否安装完整。另一个查看版本信息的方法是pip show labelImg这条命令会显示当前安装的版本号以及依赖包列表能辅助判断是否有包缺失或版本冲突。4. 从画框到导出一次完整标注流程的细节拆解标注本身不复杂但在实际项目里标注前期的准备工作和标注后的文件组织方式决定了后续训练阶段是否顺利。这一章按完整流程来走一遍每一步的参数和习惯都会说到。4.1 准备工作图片目录与类别文件的组织先把要标注的图片放进一个单独的文件夹并且规划好存放标注文件的目录。我的习惯是这样组织的D:\datasets\images\ # 存放原始图片 D:\datasets\labels\ # 存放生成的 txt 文件 D:\datasets\classes.txt # 类别列表其中classes.txt里每行放一个类别名称例如person car bicycle这份文件的作用是让标注工具在下拉菜单里能直接显示类名不用每次都手打一遍。YOLO 模式识别类别时是按classes.txt的行号来的第一行对应类别 0第二行对应类别 1以此类推。注意类别顺序一旦确定就不要随意调整否则前面标注生成的数据和后面训练时的类别索引会对不上严重影响训练效果。4.2 打开图片目录并切换标注格式打开软件后点击左侧的“打开目录”选择你存放图片的文件夹这时右侧窗口会显示第一张图片。接下来是格式选择。在界面的左侧工具栏和菜单PascalVOC处可以看到当前标注格式。点击它可以切换PascalVOC生成.xml文件YOLO生成.txt文件那段获自动生成的文本中提及按钮在左侧工具栏实际位置可能在菜单栏点击它后菜单会切换显示当前模式。切换到 YOLO 模式后需要找到菜单中的“打开类别文件”加载刚才写的classes.txt。如果这一步不做画框后选择类别时会发现下拉框里是空的只能手动输入类别名。偶尔也有朋友直接用默认类别“unknown”来标但这会在训练时造成语义混乱不推荐这样做。在实际操作中我通常先切到 YOLO 模式再加载类别文件最后打开图片目录。顺序乱了也不至于报错但按照这个顺序操作会少一些弹窗的选择麻烦。4.3 画框与类别命名核心操作和快捷键现在可以开始标注了。鼠标左键按下后拖拽即可拉出一个矩形框松开鼠标后系统会弹出类别选择对话框。此时从列表中选择或输入一个类名点击 OK 确认即可。如果想撤销上一个画错的框按CtrlZ画完后要修改框的位置选中框边缘拖拽即可调整。常用快捷键W画框D下一张A上一张CtrlS保存。缩放鼠标滚轮整体缩放方便框选小目标。若矩形框没完全贴合目标不用急按下Ctrl放大画布后微调边线即可。标注一个小技巧先标注角落目标再标中心目标。在繁忙的街景图中角落目标往往容易被漏标而摄像头画面上的边缘物体对训练结果的影响较明显。养成固定标注顺序能降低漏标的概率。4.4 保存格式与文件结构验证标注完一张图片后按CtrlS保存。此时 YOLO 模式会生成一个与图片同名的.txt文件。例如图片001.jpg对应的标注文件为001.txt。txt 文件里一行内容长这样0 0.523437 0.459821 0.173437 0.179017这行数据的含义是类别编号0、归一化中心点 x 坐标0.523437、归一化中心点 y 坐标0.459821、归一化宽度0.173437、归一化高度0.179017。这些数值全部是相对于图片宽高的比例这是 YOLO 训练格式的标准要求。验证文件是否生成成功的方法很简单打开保存目录看是否存在与图片同名的.txt文件。另外也可以直接打开其中一个文件检查数值是否在 0 到 1 之间。如果出现负数或大于 1 的异常值说明画框过程出了偏差比如跨出了图片边界应当回看原图并修正。在标注到一半时也可以随时保存再继续不用每次手动存档。CtrlS这个动作建议频繁按避免软件异常退出导致丢失刚才的工作进度。4.5 标注目录与图片目录的分离策略默认情况下LabelImg 会把标注文件放到图片所在的同一个目录。当一个文件夹里图片数量达到几千张之后混在一起的图片和 txt 会让后续的数据集制作变得难以管理。比较推荐的做法是在标注开始前就打开软件的“保存目录”选项把标注文件单独指到一个目录。如果你已经用默认方式标了不少图片也不要紧——在整理阶段写一个简单脚本把同名的 txt 迁移到 labels 目录即可import os import shutil img_dir D:/datasets/images/ label_dir D:/datasets/labels/ for file in os.listdir(img_dir): if file.endswith(.jpg): base file[:-4] txt_file os.path.join(img_dir, base .txt) if os.path.exists(txt_file): shutil.move(txt_file, os.path.join(label_dir, base .txt))这段代码的作用是遍历图片目录找到与每张图片同名的 txt 文件并将它移动到独立标签目录。参数说明os.listdir获取目录下的所有文件名os.path.exists判断同名 txt 是否存在shutil.move执行移动动作。运行前先新建好labels目录否则移动会报目标目录不存在的错误。到这里一套标准的标注流程就走完了。从打开工具到整理目录整个过程没有复杂的参数需要调整只要保持文件和标注信息的对应关系正确是完全可以顺利完成的。但请注意刚才提到的都是理想状态实际使用中还有几个隐藏的坑下面专门来讲。5. 避坑手册安装、路径与标注质量排查任何标注工具用久了都会遇到各类小问题。把这些问题一次性记录下来能帮大家在遇到类似情况时快速定位原因不用反复试错。5.1 现象输入 labelImg 命令后窗口毫无反应或立刻闪退原因大多是版本兼容或缺失依赖包。解决先检查 Python 版本3.10 及以上版本直接用 pip 安装启动时可能会报 PyQt5 不兼容导致窗口一闪而过。遇到这种情况建议改用免安装 zip 版本或者换 Python 3.9 环境。另外执行pip install --upgrade pyqt5 lxml升级依赖后再重新运行也能解决一部分闪退问题。如果这两条路都试了仍启动失败那很可能是系统库缺失常见的是某些精简版 Windows 缺少必要的 VC 运行环境。去系统设置里补装对应运行库后重试。5.2 现象打开图片目录时文件夹里只有几张图其他图片不显示原因LabelImg 默认只筛选常见图片格式比如 jpg、png、bmp。如果你的图片是 tiff 或其他少见格式工具不会在文件列表中显示。解决在文件类型筛选中手动选择“所有文件”或者预先批量把图片转为 jpg/png 格式。转换脚本一般只需几行代码我在批量前处理时最喜欢用from PIL import Image import os src_dir D:/raw_images/ dst_dir D:/datasets/images/ for file in os.listdir(src_dir): if file.lower().endswith((.tif, .bmp)): img Image.open(os.path.join(src_dir, file)) base os.path.splitext(file)[0] img.save(os.path.join(dst_dir, base .jpg), quality95)参数说明Image.open读取原图img.save将图片转换为 jpg 格式quality控制压缩质量。此处的os.path.splitext用来获取不带扩展名的文件名确保输出文件名保持与原名一致。5.3 现象YOLO 模式下保存的 txt 文件里类别编号全部是 0原因没有正确加载类别文件LabelImg 会默认把所有类别视为第一个类别。解决标注前先到打开类别文件中指定classes.txt。标注完成后抽查几个 txt 文件的内容如果类别编号长期为 0就说明类别配置这一步被跳过了。已经标错的图片无法靠改编号来直接恢复需要重新框选对应物体并修改类别因此一定要避免开始前偷懒。检查类别编号的习惯每标完 20 张左右随机打开一个 txt 文件确认类别编号在合理范围内与classes.txt对应无误。这个习惯能尽早发现问题不至于等标完全部图片才发现。5.4 现象标注过程中软件卡死或保存时报错“找不到路径”原因标注图片存放路径或保存路径包含中文、空格等特殊字符导致底层 Qt 访问文件时出现异常。解决将数据集整体移动到纯英文路径下如D:\project\data不要放在“桌面”或“我的文档”这类中文路径里。路径调整后重新打开目录这个报错基本会消失。命令示例Windows 下快速复制目录到新路径xcopy D:\桌面\原始数据 D:\project\data /E /I参数说明/E表示复制子目录并包含空目录/I表示假定目标是一个目录避免复制过程中弹确认提示。复制完后再把原数据清理掉即可。5.5 现象已保存的 rect 框无法继续调整右键菜单不弹出来原因工具进入编辑状态时若当前选中的是“浏览”模式按快捷键默认进入画框状态此时无法直接调整已有边框。解决点击左侧工具栏的选择按钮或者按CtrlJ进入编辑模式此时鼠标可点选已有框并调整。这个模式与画框模式之间的切换是新手最容易卡的一个细节。我记得第一次标注时因为不知道编辑模式的存在以为标注工具无法修改已画框只能删掉重画浪费了大量时间。后来逐渐养成了一个习惯每次标注前先确认当前是画框模式还是编辑模式通过左侧按钮的状态就能看到。6. 进阶与自训练模型配合时如何让标注工作不返工当标注数据量增长到接近千张时你一定会遇到时间成本和纠错成本的考验。这里介绍自己用的一个技巧结合预训练模型进行预标注协同减少人工画框压力。常见做法是先用一个现成的检测模型例如 YOLOv8n跑一遍未标注图片生成初步的预测框和类别概率。然后把这些预测结果以 txt 文件的形式保留下来。此时再用 LabelImg 打开对应图片你会发现左侧工具栏可以直接加载这些已有框之后要做的只是删掉错误的框、修正漏掉的目标和微调边缘。这套流程的核心逻辑是计算机先做粗标人来负责复核修正。很多大型数据集项目都用类似的方法来控制标注质量。对个人开发者来说大幅减少人工初始画框的时间是实际应用里回报最高的操作。具体操作起来我用的是 YOLO 官方提供的推理方法来生成初版预测from ultralytics import YOLO model YOLO(yolov8n.pt) results model.predict(D:/datasets/images, save_txtTrue, save_confTrue)参数说明save_txtTrue会把每个检测目标的坐标和类别写入 txt 文件生成格式与 LabelImg 的 YOLO 模式相同save_confTrue额外保存置信度。这里有个关键点YOLO 生成的 txt 中最后一列是置信度而 LabelImg 不读取置信度用 LabelImg 打开时会忽略这一列不会影响标注内容。为了更准确地协同工作还有一点值得注意预标注的类别编号必须与人工标注的classes.txt保持一致。如果预训练模型输出的类别名称与你的项目类别不完全对应需要先对类别名称进行对齐否则后面修正框的环节会混乱。举个实际例子你训练的classes.txt里第 0 类是person但预训练模型输出的 txt 中第 0 类是dog。这时如果直接打开LabelImg 会根据编号 0 显示person但实际上框住的是一只狗。这就需要通过model.names打印类名列表人工做一次映射print(model.names)然后根据输出结果写一个字典映射把预标注数据中的类别名替换为你的项目类别名。这一步虽然费点功夫但能避免大规模返工。这段技巧用一段时间后我形成了一种习惯拿到新图像集时先让预训练模型过一遍再人工复核修改。只要模型在目标类别上的初始检出效果不太差整体的标注效率都能提升不少。另一个实用习惯是在标注中途阶段就定期做一轮抽查而不是全部标完再检查。抽查方法很简单随机抽取 5% 已标注的图片打开图片和对应 txt 文件检查是否出现漏框、错框或边界框明显偏移的情况。当场发现问题当场修正比后期集中复查要省力得多。说到底LabelImg 的价值不只是让你把框画出来。真正让标注环节顺滑的是你对格式的理解、对路径和类别的控制以及对整个数据集生产流程的把握。从那以后我每次做标注前都会强制把类别文件、保存目录和图片路径这三个基础项走一遍再开始工作。事实证明这些前期准备要比任何技巧都更能避免后期返工。希望这些经验能帮你的目标检测项目顺利推进少踩几个不必要的坑。本文还有配套的精品资源点击获取