HumanSignal/labelImg · 上手攻略

• 仓库：HumanSignal/labelImg
• 链接：https://github.com/HumanSignal/labelImg
• 分类：ai · data-annotation · computer-vision
• 作者：Tom
• 更新：2026-08-18

是什么

labelImg 是一个开源的图形化图像标注工具，由 Tzutalin 开发维护，现归属 HumanSignal（Label Studio 社区）管理。它用 Python + Qt 编写，提供直观的 GUI，让用户通过鼠标框选来标注目标物体，生成标准格式的标注文件。标注结果支持 PASCAL VOC XML、YOLO TXT 和 CreateML JSON 三种主流格式，广泛用于目标检测模型的数据准备阶段。

⚠️ 注意：labelImg 已于 2023 年起停止活跃开发，官方推荐转向 Label Studio。本攻略仍详细记录 labelImg 用法，因其在小型项目和独立研究场景中仍是最高效的无依赖标注工具。

解决什么问题

训练目标检测模型（如 YOLO、Faster R-CNN）需要大量带边界框（bounding box）标注的图像数据。labelImg 解决了以下痛点：

• 人工标注效率低：无工具时标注结果难以标准化、格式不统一。
• 格式转换成本：不同框架需要不同标注格式，手动转换易出错。
• 标注结果管理：大规模图像集需要统一的标注文件组织和查看机制。
• 硬件要求：纯 Python + Qt 实现，无需 GPU，一台普通电脑即可工作。

快速安装

最简方式（推荐 Ubuntu/Linux）

pip3 install labelImg
labelImg                    # 直接启动
labelImg [IMAGE_PATH]       # 指定图像路径启动
labelImg [IMAGE_PATH] [PRE_DEFINDED_CLASS_FILE]  # 指定类别文件

Python 3 + Qt5（通用）

Ubuntu/Debian：

sudo apt-get install pyqt5-dev-tools
sudo pip3 install -r requirements/requirements-linux-python3.txt
make qt5py3
python3 labelImg.py

macOS：

brew install qt        # 通过 Homebrew 安装 Qt 5.x
brew install libxml2
# 或用 pip 代替
pip3 install pyqt5 lxml
make qt5py3
python3 labelImg.py

Windows：

# 1. 安装 Python 3 + PyQt5 + lxml
pip install PyQt5 lxml

# 2. 进入 labelImg 目录，运行资源编译
pyrcc5 -o libs/resources.py resources.qrc

# 3. 启动
python labelImg.py
python labelImg.py [IMAGE_PATH] [PRE_DEFINED_CLASS_FILE]

Docker：

docker run -it \
  --user $(id -u) \
  -e DISPLAY=unix$DISPLAY \
  --workdir=$(pwd) \
  --volume="/home/$USER:/home/$USER" \
  --volume="/tmp/.X11-unix:/tmp/.X11-unix" \
  tzutalin/py2qt4
make qt4py2; ./labelImg.py

⚠️ PyQt4 vs PyQt5：PyQt4 已停止维护，新系统建议统一使用 PyQt5。编译资源文件时，pyrcc4 用于 PyQt4，pyrcc5 用于 PyQt5。

核心用法

基本标注流程

1. 启动 labelImg 后，点击 File → Change default saved annotation folder 设置标注文件保存目录。
2. 点击 Open Dir 选择图像所在文件夹。
3. 按 W 键（或点击工具栏 Create RectBox）。
4. 鼠标框选目标物体。
5. 在弹出框输入类别名（或从预定义列表选择）。
6. 按 Ctrl + S 保存。

快捷键一览

预定义类别文件

编辑 data/predefined_classes.txt，每行一个类别名：

person
car
dog
cat
bicycle

启动时指定该文件：

labelImg path/to/images path/to/predefined_classes.txt

导出 YOLO 格式

1. 在 data/predefined_classes.txt 定义类别列表。
2. 启动 labelImg。
3. 在工具栏 Save 按钮右侧，点击 PascalVOC 按钮切换为 YOLO 格式。
4. 正常标注并保存。

YOLO 格式下，标注文件为同名 .txt，每行格式为：

<class_id> <x_center> <y_center> <width> <height>

坐标均为相对于图像尺寸的归一化值（0~1）。同目录下会额外生成 classes.txt 记录类别顺序。

⚠️ 重要： - 标注中途切换类别列表会导致已有标注与新 classes.txt 不对应，不要在标注过程中修改类别列表。 - YOLO 格式下"difficult"标志会被丢弃。

批量标注与已有标注导入

将已有的标签文件（与图像同名，放入同目录），然后点击 File → Open Dir，labelImg 会自动加载已有标注并显示边界框。这一功能适合继续之前未完成的标注工作。

典型适用场景

• 训练 YOLO / Faster R-CNN / SSD 等检测模型前的数据标注：最常见的用法，快速产出 VOC 或 YOLO 格式标注文件。
• 小规模数据集标注（< 10,000 张）：不需要部署完整的 Label Studio，一键安装即可工作。
• 数据集质量审核：用 "Verify Image" 功能（按 Space）快速浏览已标注图像，标记需要修正的样本。
• 跨格式数据集转换：标注一份，通过切换输出格式快速生成多套标注文件（VOC / YOLO / CreateML）。

坑与注意

1. labelImg 已停止维护：2023 年起不再更新，但 PyPI 仍可安装。遇到 Qt 版本问题时，建议在虚拟环境中隔离安装。
2. PyQt4 / PyQt5 版本混乱：部分 Linux 发行版预装 PyQt4，会导致 pyrcc5 编译错误。先确认系统 Qt 版本，再选择对应的 pyrcc 工具。
3. macOS Apple Silicon（M1/M2/M3）：通过 Homebrew 安装 Qt 时注意架构兼容，建议用 pip 安装 PyQt5 而非 Homebrew Qt 以避免跨架构问题。
4. 标注格式切换时 classes.txt 覆盖：切换 PascalVOC → YOLO 时，同目录的 classes.txt 会被覆盖。如需保留多个格式，建议分目录标注。
5. 中文路径支持：labelImg 对含中文的路径支持较好，但仍建议使用纯 ASCII 路径避免潜在问题。
6. 大规模标注（> 10,000 张）：labelImg 无项目管理、协作或审查工作流，强烈建议转向 Label Studio。
7. 自动保存：labelImg 不自动保存，每次标注后必须按 Ctrl+S，否则关闭后数据丢失。

与同类对比

一句话推荐结论

labelImg 是小规模目标检测标注的首选工具——零配置、pip 即装即用、VOC/YOLO 双格式导出；但已停止维护，大型项目请直接上 Label Studio 或 CVAT。