前言在计算机视觉（CV）项目的全流程中，数据标注是决定模型效果的核心环节——高质量的标注数据是算法模型精准训练的基础。labelImg 作为一款轻量级、开源免费的图形化图像标注工具，凭借简洁的操作界面、对 Pascal VOC/YOLO 主流标注格式的原生支持，以及跨平台特性，成为 CV 从业者处理目标检测标注任务的首选工具。
本文基于 labelImg 官方源码仓库，从安装部署、基础操作、高级功能、故障排除到效率优化，全方位讲解 labelImg 的使用方法，帮助您快速掌握这款工具并大幅提升标注效率。
一、快速开始1.1 安装与运行labelImg 提供两种使用方式：免安装可执行文件（适合普通用户）和源码运行（适合开发者/定制化需求）。
Windows 用户（推荐）从 Gitee 发布页 下载 labelImg-2.0.0.exe
双击直接运行，无需安装 Python 或任何依赖
（可选）将程序创建桌面快捷方式，方便日常使用
macOS 用户下载 labelImg-2.0.0.dmg 镜像文件
双击打开镜像，将 labelImg.app 拖拽到 Applications 文件夹
首次运行若提示"无法验证开发者"，右键选择"打开"（macOS 安全机制）
Linux 用户# 安装依赖sudo apt-get install python3-pyqt5 pyqt5-dev-toolspip3 install lxml# 克隆仓库git clone https://gitee.com/tekintian/labelImg.gitcd labelImg# 编译资源文件pyrcc5 -o resources.py resources.qrc# 运行python3 labelImg.py从源码运行（全平台通用）# 克隆仓库（Gitee 国内访问更快）git clone https://gitee.com/tekintian/labelImg.gitcd labelImg# 安装依赖（建议使用虚拟环境）pip install -r requirements.txt# 生成资源文件（关键步骤，缺失会导致图标/语言包加载失败）pyrcc5 -o resources.py resources.qrc# 启动应用python labelImg.py1.2 界面概览labelImg 界面采用极简设计，核心区域划分清晰：
区域功能描述顶部菜单栏文件操作、格式切换、语言设置、视图控制等核心功能工具栏常用操作快捷按钮（打开、保存、创建标注框、验证等）左侧面板标注框列表、默认标签设置、难度标注控制中央画布图像显示与标注绘制核心区域，支持缩放/平移底部状态栏显示图像路径、尺寸、标注数量、操作提示等信息💡 提示：首次运行建议先查看「帮助」菜单下的「快捷键列表」，熟练使用快捷键可提升 50% 以上标注效率。
二、基础操作2.1 图像加载单张图像加载文件 → 打开 (Ctrl+O)支持格式：JPG、PNG、BMP、TIFF 等主流图像格式，路径建议使用英文（避免中文路径导致加载失败）。
批量图像加载（推荐）文件 → 打开目录 (Ctrl+R)选择包含图像的文件夹后：
按 D 键切换到下一张图像
按 A 键切换到上一张图像
底部状态栏会显示「当前/总数量」（如：1/100）
💡 最佳实践：将待标注图像统一放在 dataset/images 目录，标注文件会自动保存在同目录（或自定义 dataset/annotations）。
2.2 创建标注框标准流程按 W 键（或点击工具栏「创建矩形框」按钮）进入绘制模式
在目标对象区域按住左键拖拽，绘制包围目标的矩形框
松开鼠标后弹出标签输入框，输入类别名称（如 person、car）
按 Enter 确认（或点击「确定」按钮），标注框创建完成
实用技巧拖拽时按住 Shift 键：强制绘制正方形标注框
绘制中按 Esc 键：取消当前标注框绘制
输入标签时按 Tab 键：自动联想预定义标签（需配置 3.2 节）
2.3 标注框编辑调整位置/大小选中标注框：点击标注框任意位置，框体出现控制点（8个小方块）
调整大小：拖拽四个角/边的控制点，精准匹配目标边界
移动位置：拖拽标注框内部区域，整体平移（无需重新绘制）
修改标签方法1：双击标注框 → 直接编辑标签文本
方法2：左侧列表双击标注框条目 → 修改标签
方法3：选中标注框 → 右键 → 「编辑标签」
删除标注框单框删除：选中标注框 → 按 Delete 键（或右键→「删除」）
全图清空：编辑 → 删除所有标注 (Ctrl+Delete)
2.4 标注保存手动保存文件 → 保存 (Ctrl+S)Pascal VOC 格式：生成与图像同名的 .xml 文件
YOLO 格式：生成与图像同名的 .txt 文件
另存为文件 → 另存为 (Ctrl+Shift+S)自定义标注文件保存路径（适合需要分离图像与标注文件的场景）。
自动保存（推荐）视图 → 自动保存启用后：
切换图像（A/D）时自动保存当前标注
避免因忘记保存导致标注数据丢失
批量标注时必备功能
三、高级功能3.1 标注格式切换labelImg 原生支持两种工业级标注格式，可随时切换：
Pascal VOC XML 格式（默认）文件 → 切换保存格式 → PascalVOC适用场景：TensorFlow、PyTorch 通用检测框架、VOC 竞赛数据集
文件结构：
格式说明：
# 每行格式：类别ID x_center y_center width height（均归一化到 0-1）0 0.5 0.5 0.4 0.3 # person 类别，中心坐标(0.5,0.5)，宽0.4，高0.3⚠️ 关键注意事项：
YOLO 格式依赖 data/predefined_classes.txt 定义类别列表（类别ID按文件中行数排序）
坐标自动归一化（无需手动计算）
标注文件与图像文件必须同名，放在同一目录（或按 YOLO 标准目录结构）
3.2 预定义标签（效率神器）预先定义常用标签，避免重复输入，大幅提升标注效率。
设置方法打开 labelImg/data/predefined_classes.txt 文件
每行输入一个标签名称（按使用频率排序）：
personcarbicycledogcatbustruck保存文件并重启 labelImg
创建标注框时，标签输入框会自动弹出下拉选择列表
💡 进阶技巧：不同项目可创建多个标签文件（如 classes_traffic.txt、classes_face.txt），使用时替换 predefined_classes.txt 即可。
3.3 默认标签功能适用于单类别标注场景（如仅标注「person」），无需每次输入标签：
在左侧面板底部勾选「使用默认标签」
在输入框中填写默认标签（如 person）
后续创建的所有标注框将自动使用该标签
3.4 难度标注用于标记模糊、遮挡、难以识别的目标，标注信息会写入 Pascal VOC 格式的
操作方法选中标注框
右键 → 「标记为困难」（或按 Ctrl+D）
标注框变为虚线样式，表示已标记为困难样本
📌 用途：训练模型时可选择跳过困难样本，或单独处理这类数据。
3.5 标注验证快速检查数据集标注完成情况，避免遗漏：
点击工具栏「验证」按钮（或按 Ctrl+V）
应用自动检测当前图像是否有标注框：
有标注：状态栏显示「已验证」，按 D 键跳过
无标注：状态栏显示红色警告「未标注」
批量验证：打开目录后，连续按 D 键快速扫描所有图像
3.6 撤销/重做标注错误时快速回退，无需手动删除：
撤销：Ctrl+Z（撤销上一步标注操作）
重做：Ctrl+Y / Ctrl+Shift+Z（恢复撤销的操作）
四、快捷键大全（速查版）核心操作（必记）快捷键功能使用场景W创建矩形框开始标注目标D下一张图像批量标注切换A上一张图像批量标注回溯Ctrl+S保存标注手动保存当前标注Delete删除标注框移除错误标注Ctrl+Z撤销恢复上一步操作文件操作快捷键功能Ctrl+O打开单张图像Ctrl+R打开图像目录Ctrl+Shift+S标注另存为Ctrl+Q退出应用视图控制快捷键功能Ctrl++放大图像Ctrl+-缩小图像Ctrl+0适应窗口显示Ctrl+1适应宽度显示鼠标滚轮画布缩放编辑操作快捷键功能Ctrl+D标记/取消困难标注Ctrl+Delete删除所有标注框Ctrl+C复制标注框Ctrl+V粘贴标注框Ctrl+X剪切标注框五、视图与个性化设置5.1 画布缩放控制精准缩放：使用 Ctrl++/Ctrl+- 或工具栏缩放按钮
快速适配：
Ctrl+0：自动调整图像大小适配窗口（推荐）
Ctrl+1：仅适配宽度，保持宽高比
手动平移：按住鼠标右键拖拽画布（图像放大后）
5.2 标注框样式自定义颜色设置视图 → 框线颜色选择自定义颜色后，新创建的标注框将使用该颜色（历史标注框颜色不变），便于区分不同类别或标注阶段。
显示选项视图 → 显示选项可配置：
✅ 显示标签文本（默认开启）
✅ 显示标注框序号（便于计数）
✅ 显示十字准星（辅助精准定位）
✅ 显示边界框（核心，不可关闭）
5.3 多语言支持labelImg 内置三种语言，切换步骤：
语言 → English / 简体中文 / 繁体中文
重启应用使设置生效
自定义语言（进阶）在 resources/strings/ 目录创建 strings-xx-XX.properties（如 strings-ja.properties 日语）
复制 strings.properties 内容并翻译所有键值对
修改 resources.qrc，添加新语言文件路径
重新编译资源：pyrcc5 -o resources.py resources.qrc
六、工作流最佳实践6.1 标准化标注流程步骤1：数据准备dataset/├── images/ # 原始图像（统一格式为 JPG/PNG）│ ├── 001.jpg│ ├── 002.jpg│ └── ...├── annotations/ # 标注文件（自动生成）└── classes.txt # YOLO 类别文件（可选）步骤2：工具配置编辑 predefined_classes.txt，添加项目所需标签
选择标注格式（Pascal VOC/YOLO）
启用「自动保存」功能
设置默认标签（单类别标注）
步骤3：高效标注打开目录 → 按 W 绘制标注框 → 按 Enter 确认 → 按 D 下一张步骤4：质量检查使用「验证」功能扫描未标注图像
随机抽样检查标注框精度（边界是否贴合目标）
统计标签分布，确保数据均衡
6.2 团队协作标注任务拆分按图像编号拆分：如 A 负责 001-500，B 负责 501-1000
按类别拆分：如 A 标注「person」，B 标注「car」（适合多类别场景）
规范统一共享 predefined_classes.txt，确保标签命名一致
约定标注框绘制规范（如框体需完全包围目标，不裁剪）
使用版本控制（Git）管理标注文件，避免覆盖
质量管控交叉检查：每人随机检查对方 10% 的标注数据
标注规范文档：记录特殊情况处理规则（如遮挡目标如何标注）
6.3 YOLO 格式标注专项指南必备配置创建 classes.txt，按类别优先级排序：
person # ID=0car # ID=1bike # ID=2将 classes.txt 放入 data 目录，替换 predefined_classes.txt
切换保存格式为 YOLO
格式验证编写脚本检查标注文件是否符合 YOLO 规范：
import osdef check_yolo_format(txt_path, img_width, img_height): """验证 YOLO 标注格式是否正确""" with open(txt_path, 'r') as f: lines = f.readlines() for line in lines: parts = line.strip().split() # 检查字段数量 if len(parts) != 5: return False, f"字段数量错误：{line}" # 检查坐标范围（0-1） try: class_id = int(parts[0]) x, y, w, h = map(float, parts[1:]) if not (0 <= x <= 1 and 0 <= y <= 1 and 0 <= w <= 1 and 0 <= h <= 1): return False, f"坐标超出范围：{line}" except ValueError: return False, f"格式错误：{line}" return True, "格式正确"# 使用示例# check_yolo_format("annotations/001.txt", 1920, 1080)七、常见问题与故障排除7.1 启动类问题问题现象原因分析解决方案运行提示「缺少 resources 模块」未编译资源文件执行 pyrcc5 -o resources.py resources.qrcPyQt5 导入错误依赖未安装/版本不兼容pip install PyQt5==5.15.9（稳定版本）macOS 提示「无法打开」系统安全设置右键 → 打开 → 确认「仍要打开」Linux 运行闪退缺少 Qt 运行库sudo apt-get install libqt5gui57.2 功能类问题问题现象原因分析解决方案标注框无法保存目录无写入权限更换保存目录（如桌面）YOLO 标注文件为空标签不在 predefined_classes.txt 中检查标签名称是否匹配中文路径图像加载失败PyQt 对中文路径支持有限将图像/文件夹重命名为英文快捷键无响应焦点在输入框/其他组件点击画布空白处，确保焦点在主窗口7.3 性能类问题问题现象原因分析解决方案大图像（4K/8K）加载卡顿内存占用过高1. 缩放后标注（Ctrl+0）
2. 关闭其他后台程序
3. 预处理缩小图像分辨率批量标注切换图像缓慢硬盘读写速度慢1. 将数据集移至 SSD
2. 关闭自动保存（手动批量保存）界面闪烁/卡顿显卡驱动问题更新显卡驱动，或关闭反锯齿渲染八、进阶技巧与效率优化8.1 标注效率提升技巧标签快速选择：预定义标签按使用频率排序，常用标签放在前3行
标注框复用：相同目标在连续图像中位置相近时，使用 Ctrl+C/V 复制粘贴后微调
批量重命名：使用脚本统一图像命名格式（如 0001.jpg、0002.jpg），便于管理
自动标注辅助：结合简易脚本生成候选标注框（如基于颜色/轮廓检测），手动调整
8.2 标注数据统计与分析标签分布统计（Pascal VOC 格式）import osimport xml.etree.ElementTree as ETdef count_voc_labels(anno_dir): """统计 VOC 标注文件中各标签数量""" label_count = {} for xml_file in os.listdir(anno_dir): if not xml_file.endswith('.xml'): continue tree = ET.parse(os.path.join(anno_dir, xml_file)) root = tree.getroot() for obj in root.findall('object'): label = obj.find('name').text label_count[label] = label_count.get(label, 0) + 1 print("=== 标注标签统计 ===") for label, count in sorted(label_count.items()): print(f"{label}: {count}") print(f"总计标注框：{sum(label_count.values())}")# 使用：统计 annotations 目录下的标签count_voc_labels("dataset/annotations")YOLO 格式标注统计def count_yolo_labels(txt_dir, classes_file): """统计 YOLO 标注文件标签分布""" # 加载类别映射 with open(classes_file, 'r') as f: classes = [line.strip() for line in f.readlines()] label_count = {cls:0 for cls in classes} for txt_file in os.listdir(txt_dir): if not txt_file.endswith('.txt'): continue with open(os.path.join(txt_dir, txt_file), 'r') as f: lines = f.readlines() for line in lines: class_id = int(line.strip().split()[0]) label = classes[class_id] label_count[label] += 1 print("=== YOLO 标注统计 ===") for label, count in label_count.items(): print(f"{label}: {count}")# 使用示例# count_yolo_labels("dataset/annotations", "data/classes.txt")8.3 自定义功能开发（开发者向）新增标注格式（如 COCO）参考 libs/pascal_voc_io.py/libs/yolo_io.py，实现 COCO 格式的读写类
在 labelImg.py 中添加格式切换菜单
编译测试，确保标注数据正确生成
批量处理脚本import osimport shutildef batch_convert_format(input_dir, output_dir, from_format="voc", to_format="yolo"): """批量转换标注格式（需自行实现核心转换逻辑）""" if not os.path.exists(output_dir): os.makedirs(output_dir) for file in os.listdir(input_dir): if from_format == "voc" and file.endswith('.xml'): # 转换 XML 到 TXT（YOLO） basename = os.path.splitext(file)[0] # 核心转换逻辑... # save to output_dir/{basename}.txt九、总结labelImg 凭借轻量化、易操作、跨平台的特性，成为目标检测标注的首选工具。掌握以下核心要点，可大幅提升标注效率与数据质量：
快捷键是效率核心：熟练使用 W/D/A/Ctrl+S 等核心快捷键
预配置提升体验：提前设置预定义标签、默认标签、自动保存
格式选择匹配场景：Pascal VOC 通用，YOLO 适配 YOLO 系列模型
质量控制不可少：标注后验证、抽样检查、统计分析
通过本文的指南，您已掌握 labelImg 从基础到进阶的全部使用技巧。如需定制化功能或技术支持，可参考项目源码进行二次开发，或联系项目维护者获取帮助。
参考资源官方仓库：Gitee（https://gitee.com/tekintian/labelImg）、GitHub（https://github.com/tekintian/labelImg）
Pascal VOC 格式规范：http://host.robots.ox.ac.uk/pascal/VOC/
YOLO 格式说明：https://docs.ultralytics.com/datasets/detect/
PyQt5 开发文档：https://www.riverbankcomputing.com/static/Docs/PyQt5/