labelImg 图像标注工具完全指南：从入门到精通

前言

在计算机视觉（CV）项目的全流程中，数据标注是决定模型效果的核心环节——高质量的标注数据是算法模型精准训练的基础。labelImg 作为一款轻量级、开源免费的图形化图像标注工具，凭借简洁的操作界面、对 Pascal VOC/YOLO 主流标注格式的原生支持，以及跨平台特性，成为 CV 从业者处理目标检测标注任务的首选工具。

本文基于 labelImg 官方源码仓库，从安装部署、基础操作、高级功能、故障排除到效率优化，全方位讲解 labelImg 的使用方法，帮助您快速掌握这款工具并大幅提升标注效率。

一、快速开始

1.1 安装与运行

labelImg 提供两种使用方式：免安装可执行文件（适合普通用户）和源码运行（适合开发者/定制化需求）。

Windows 用户（推荐）

1. 从 Gitee 发布页 下载 labelImg-2.0.0.exe

2. 双击直接运行，无需安装 Python 或任何依赖

3. （可选）将程序创建桌面快捷方式，方便日常使用

macOS 用户

1. 下载 labelImg-2.0.0.dmg 镜像文件

2. 双击打开镜像，将 labelImg.app 拖拽到 Applications 文件夹

3. 首次运行若提示"无法验证开发者"，右键选择"打开"（macOS 安全机制）

Linux 用户

# 安装依赖
sudo apt-get install python3-pyqt5 pyqt5-dev-tools
pip3 install lxml
​
# 克隆仓库
git clone https://gitee.com/tekintian/labelImg.git
cd labelImg
​
# 编译资源文件
pyrcc5 -o resources.py resources.qrc
​
# 运行
python3 labelImg.py

从源码运行（全平台通用）

# 克隆仓库（Gitee 国内访问更快）
git clone https://gitee.com/tekintian/labelImg.git
cd labelImg
​
# 安装依赖（建议使用虚拟环境）
pip install -r requirements.txt
​
# 生成资源文件（关键步骤，缺失会导致图标/语言包加载失败）
pyrcc5 -o resources.py resources.qrc
​
# 启动应用
python labelImg.py

1.2 界面概览

labelImg 界面采用极简设计，核心区域划分清晰：

💡 提示：首次运行建议先查看「帮助」菜单下的「快捷键列表」，熟练使用快捷键可提升 50% 以上标注效率。

二、基础操作

2.1 图像加载

单张图像加载

文件 → 打开 (Ctrl+O)

支持格式：JPG、PNG、BMP、TIFF 等主流图像格式，路径建议使用英文（避免中文路径导致加载失败）。

批量图像加载（推荐）

文件 → 打开目录 (Ctrl+R)

选择包含图像的文件夹后：

• 按 D 键切换到下一张图像

• 按 A 键切换到上一张图像

• 底部状态栏会显示「当前/总数量」（如：1/100）

💡 最佳实践：将待标注图像统一放在 dataset/images 目录，标注文件会自动保存在同目录（或自定义 dataset/annotations）。

2.2 创建标注框

标准流程

1. 按 W 键（或点击工具栏「创建矩形框」按钮）进入绘制模式

2. 在目标对象区域按住左键拖拽，绘制包围目标的矩形框

3. 松开鼠标后弹出标签输入框，输入类别名称（如 person、car）

4. 按 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 竞赛数据集 文件结构：

<annotation>
  <folder>images</folder>
  <filename>img001.jpg</filename>
  <size>
    <width>1920</width>
    <height>1080</height>
    <depth>3</depth>
  </size>
  <object>
    <name>person</name>  <!-- 标签名称 -->
    <difficult>0</difficult>  <!-- 难度标注 -->
    <bndbox>
      <xmin>100</xmin>  <!-- 左上角X -->
      <ymin>200</ymin>  <!-- 左上角Y -->
      <xmax>300</xmax>  <!-- 右下角X -->
      <ymax>400</ymax>  <!-- 右下角Y -->
    </bndbox>
  </object>
</annotation>

YOLO 格式

文件 → 切换保存格式 → YOLO

适用场景：YOLOv3/v4/v5/v8 系列模型 格式说明：

# 每行格式：类别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

⚠️ 关键注意事项：

1. YOLO 格式依赖 data/predefined_classes.txt 定义类别列表（类别ID按文件中行数排序）

2. 坐标自动归一化（无需手动计算）

3. 标注文件与图像文件必须同名，放在同一目录（或按 YOLO 标准目录结构）

3.2 预定义标签（效率神器）

预先定义常用标签，避免重复输入，大幅提升标注效率。

设置方法

1. 打开 labelImg/data/predefined_classes.txt 文件

2. 每行输入一个标签名称（按使用频率排序）：

   person
   car
   bicycle
   dog
   cat
   bus
   truck

3. 保存文件并重启 labelImg

4. 创建标注框时，标签输入框会自动弹出下拉选择列表

💡 进阶技巧：不同项目可创建多个标签文件（如 classes_traffic.txt、classes_face.txt），使用时替换 predefined_classes.txt 即可。

3.3 默认标签功能

适用于单类别标注场景（如仅标注「person」），无需每次输入标签：

1. 在左侧面板底部勾选「使用默认标签」

2. 在输入框中填写默认标签（如 person）

3. 后续创建的所有标注框将自动使用该标签

3.4 难度标注

用于标记模糊、遮挡、难以识别的目标，标注信息会写入 Pascal VOC 格式的 <difficult> 字段：

操作方法

1. 选中标注框

2. 右键 → 「标记为困难」（或按 Ctrl+D）

3. 标注框变为虚线样式，表示已标记为困难样本

📌 用途：训练模型时可选择跳过困难样本，或单独处理这类数据。

3.5 标注验证

快速检查数据集标注完成情况，避免遗漏：

1. 点击工具栏「验证」按钮（或按 Ctrl+V）

2. 应用自动检测当前图像是否有标注框：

   • 有标注：状态栏显示「已验证」，按 D 键跳过

   • 无标注：状态栏显示红色警告「未标注」

3. 批量验证：打开目录后，连续按 D 键快速扫描所有图像

3.6 撤销/重做

标注错误时快速回退，无需手动删除：

• 撤销：Ctrl+Z（撤销上一步标注操作）

• 重做：Ctrl+Y / Ctrl+Shift+Z（恢复撤销的操作）

四、快捷键大全（速查版）

核心操作（必记）

文件操作

视图控制

编辑操作

五、视图与个性化设置

5.1 画布缩放控制

• 精准缩放：使用 Ctrl++/Ctrl+- 或工具栏缩放按钮

• 快速适配：

  • Ctrl+0：自动调整图像大小适配窗口（推荐）

  • Ctrl+1：仅适配宽度，保持宽高比

• 手动平移：按住鼠标右键拖拽画布（图像放大后）

5.2 标注框样式自定义

颜色设置

视图 → 框线颜色

选择自定义颜色后，新创建的标注框将使用该颜色（历史标注框颜色不变），便于区分不同类别或标注阶段。

显示选项

视图 → 显示选项

可配置：

• ✅ 显示标签文本（默认开启）

• ✅ 显示标注框序号（便于计数）

• ✅ 显示十字准星（辅助精准定位）

• ✅ 显示边界框（核心，不可关闭）

5.3 多语言支持

labelImg 内置三种语言，切换步骤：

1. 语言 → English / 简体中文 / 繁体中文

2. 重启应用使设置生效

自定义语言（进阶）

1. 在 resources/strings/ 目录创建 strings-xx-XX.properties（如 strings-ja.properties 日语）

2. 复制 strings.properties 内容并翻译所有键值对

3. 修改 resources.qrc，添加新语言文件路径

4. 重新编译资源：pyrcc5 -o resources.py resources.qrc

六、工作流最佳实践

6.1 标准化标注流程

步骤1：数据准备

dataset/
├── images/          # 原始图像（统一格式为 JPG/PNG）
│   ├── 001.jpg
│   ├── 002.jpg
│   └── ...
├── annotations/     # 标注文件（自动生成）
└── classes.txt      # YOLO 类别文件（可选）

步骤2：工具配置

1. 编辑 predefined_classes.txt，添加项目所需标签

2. 选择标注格式（Pascal VOC/YOLO）

3. 启用「自动保存」功能

4. 设置默认标签（单类别标注）

步骤3：高效标注

打开目录 → 按 W 绘制标注框 → 按 Enter 确认 → 按 D 下一张

步骤4：质量检查

1. 使用「验证」功能扫描未标注图像

2. 随机抽样检查标注框精度（边界是否贴合目标）

3. 统计标签分布，确保数据均衡

6.2 团队协作标注

任务拆分

• 按图像编号拆分：如 A 负责 001-500，B 负责 501-1000

• 按类别拆分：如 A 标注「person」，B 标注「car」（适合多类别场景）

规范统一

1. 共享 predefined_classes.txt，确保标签命名一致

2. 约定标注框绘制规范（如框体需完全包围目标，不裁剪）

3. 使用版本控制（Git）管理标注文件，避免覆盖

质量管控

• 交叉检查：每人随机检查对方 10% 的标注数据

• 标注规范文档：记录特殊情况处理规则（如遮挡目标如何标注）

6.3 YOLO 格式标注专项指南

必备配置

1. 创建 classes.txt，按类别优先级排序：

   person  # ID=0
   car     # ID=1
   bike    # ID=2

2. 将 classes.txt 放入 data 目录，替换 predefined_classes.txt

3. 切换保存格式为 YOLO

格式验证

编写脚本检查标注文件是否符合 YOLO 规范：

import os
​
def 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 启动类问题

7.2 功能类问题

7.3 性能类问题

八、进阶技巧与效率优化

8.1 标注效率提升技巧

1. 标签快速选择：预定义标签按使用频率排序，常用标签放在前3行

2. 标注框复用：相同目标在连续图像中位置相近时，使用 Ctrl+C/V 复制粘贴后微调

3. 批量重命名：使用脚本统一图像命名格式（如 0001.jpg、0002.jpg），便于管理

4. 自动标注辅助：结合简易脚本生成候选标注框（如基于颜色/轮廓检测），手动调整

8.2 标注数据统计与分析

标签分布统计（Pascal VOC 格式）

import os
import xml.etree.ElementTree as ET
​
def 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）

1. 参考 libs/pascal_voc_io.py/libs/yolo_io.py，实现 COCO 格式的读写类

2. 在 labelImg.py 中添加格式切换菜单

3. 编译测试，确保标注数据正确生成

批量处理脚本

import os
import shutil
​
def 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 凭借轻量化、易操作、跨平台的特性，成为目标检测标注的首选工具。掌握以下核心要点，可大幅提升标注效率与数据质量：

1. 快捷键是效率核心：熟练使用 W/D/A/Ctrl+S 等核心快捷键

2. 预配置提升体验：提前设置预定义标签、默认标签、自动保存

3. 格式选择匹配场景：Pascal VOC 通用，YOLO 适配 YOLO 系列模型

4. 质量控制不可少：标注后验证、抽样检查、统计分析

通过本文的指南，您已掌握 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/