简介：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 模式下生成 XML，YOLO 模式下生成 TXT。训练脚本读取这些文件后，才能把“第几张图、哪个位置、属于什么类”的信息和图片像素关联起来。
这个工具的定位不是复杂的版本管理或多人协作，而是单机完成标注的轻量场景。你不需要部署服务端、不需要申请账号、不需要考虑数据库配置，装好就能用。对于个人项目、课程设计和几万张以内的小规模数据集，它的性价比是最高的。
2.2 为什么还用老工具，而不是直接用现代标注平台
现在确实有越来越多功能丰富的标注工具，比如自动分割、标签推荐、云端协同等。但选型要看场景：
- 数据敏感性：如果你做的是学校课题或者公司内部项目，图片不方便上传到第三方平台，本地工具更稳妥。
- 格式兼容便捷性：LabelImg 生成的文件结构与目标检测任务中常见的 YOLO 训练格式几乎是标准化的。而很多平台导出时还要再经过一次格式转换，增加出错的概率。
- 硬件门槛：它只需要一台能跑 PyQt 的普通电脑，不需要 GPU，也不需要特别高的配置。教室里的老旧台式机同样能跑。
我做课程设计时常用的组合是 LabelImg 做标注 + 一份 YOLO 训练代码。标注完成后把图片和 txt 文件按目录整理好，直接就能开始训练，中间不需要写额外的转换脚本。这种“即标即用”的体验，让我一直舍不得换成更重的方案。
3. 安装的三种路径：pip、源码编译与免安装 exe
安装这一步对新手来说是最容易卡住的。因为 LabelImg 的官方文档主要面向 Linux，Windows 用户如果直接照搬命令，很可能会在安装 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 确认即可。如果想撤销上一个画错的框，按Ctrl+Z；画完后要修改框的位置，选中框边缘拖拽即可调整。
- 常用快捷键：
W画框，D下一张，A上一张，Ctrl+S保存。 - 缩放：鼠标滚轮整体缩放，方便框选小目标。
- 若矩形框没完全贴合目标，不用急，按下
Ctrl+放大画布后微调边线即可。
标注一个小技巧：先标注角落目标，再标中心目标。在繁忙的街景图中，角落目标往往容易被漏标，而摄像头画面上的边缘物体对训练结果的影响较明显。养成固定标注顺序，能降低漏标的概率。
4.4 保存格式与文件结构验证
标注完一张图片后，按Ctrl+S保存。此时 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 的异常值，说明画框过程出了偏差，比如跨出了图片边界，应当回看原图并修正。
在标注到一半时，也可以随时保存再继续，不用每次手动存档。Ctrl+S这个动作建议频繁按，避免软件异常退出导致丢失刚才的工作进度。
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"), quality=95)参数说明：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 框无法继续调整，右键菜单不弹出来
原因：工具进入编辑状态时，若当前选中的是“浏览”模式，按快捷键默认进入画框状态，此时无法直接调整已有边框。
解决：点击左侧工具栏的选择按钮，或者按Ctrl+J进入编辑模式，此时鼠标可点选已有框并调整。这个模式与画框模式之间的切换，是新手最容易卡的一个细节。
我记得第一次标注时，因为不知道编辑模式的存在，以为标注工具无法修改已画框，只能删掉重画，浪费了大量时间。后来逐渐养成了一个习惯：每次标注前先确认当前是画框模式还是编辑模式，通过左侧按钮的状态就能看到。
6. 进阶：与自训练模型配合时，如何让标注工作不返工
当标注数据量增长到接近千张时，你一定会遇到时间成本和纠错成本的考验。这里介绍自己用的一个技巧：结合预训练模型进行预标注协同，减少人工画框压力。
常见做法是先用一个现成的检测模型（例如 YOLOv8n）跑一遍未标注图片，生成初步的预测框和类别概率。然后把这些预测结果以 txt 文件的形式保留下来。此时再用 LabelImg 打开对应图片，你会发现左侧工具栏可以直接加载这些已有框，之后要做的只是删掉错误的框、修正漏掉的目标和微调边缘。
这套流程的核心逻辑是：计算机先做粗标，人来负责复核修正。很多大型数据集项目都用类似的方法来控制标注质量。对个人开发者来说，大幅减少人工初始画框的时间是实际应用里回报最高的操作。
具体操作起来，我用的是 YOLO 官方提供的推理方法来生成初版预测：
from ultralytics import YOLO model = YOLO("yolov8n.pt") results = model.predict("D:/datasets/images", save_txt=True, save_conf=True)参数说明：save_txt=True会把每个检测目标的坐标和类别写入 txt 文件，生成格式与 LabelImg 的 YOLO 模式相同；save_conf=True额外保存置信度。这里有个关键点：YOLO 生成的 txt 中最后一列是置信度，而 LabelImg 不读取置信度，用 LabelImg 打开时会忽略这一列，不会影响标注内容。
为了更准确地协同工作，还有一点值得注意：预标注的类别编号必须与人工标注的classes.txt保持一致。如果预训练模型输出的类别名称与你的项目类别不完全对应，需要先对类别名称进行对齐，否则后面修正框的环节会混乱。
举个实际例子：你训练的classes.txt里第 0 类是person，但预训练模型输出的 txt 中第 0 类是dog。这时如果直接打开，LabelImg 会根据编号 0 显示person，但实际上框住的是一只狗。这就需要通过model.names打印类名列表，人工做一次映射：
print(model.names)然后根据输出结果写一个字典映射，把预标注数据中的类别名替换为你的项目类别名。这一步虽然费点功夫，但能避免大规模返工。
这段技巧用一段时间后，我形成了一种习惯：拿到新图像集时，先让预训练模型过一遍，再人工复核修改。只要模型在目标类别上的初始检出效果不太差，整体的标注效率都能提升不少。
另一个实用习惯是在标注中途阶段就定期做一轮抽查，而不是全部标完再检查。抽查方法很简单：随机抽取 5% 已标注的图片，打开图片和对应 txt 文件，检查是否出现漏框、错框或边界框明显偏移的情况。当场发现问题，当场修正，比后期集中复查要省力得多。
说到底，LabelImg 的价值不只是让你把框画出来。真正让标注环节顺滑的，是你对格式的理解、对路径和类别的控制，以及对整个数据集生产流程的把握。从那以后我每次做标注前都会强制把类别文件、保存目录和图片路径这三个基础项走一遍，再开始工作。事实证明，这些前期准备要比任何技巧都更能避免后期返工。希望这些经验能帮你的目标检测项目顺利推进，少踩几个不必要的坑。
本文还有配套的精品资源，点击获取
