roLabelImg 详细安装教程

📌 简介

roLabelImg 是一款基于 labelImg 重写的开源图形图像标注工具，专门用于标注旋转矩形框（Rotated Bounding Box），广泛应用于遥感图像目标检测（如 DOTA 数据集）等场景。

GitHub 地址：https://github.com/cgvict/roLabelImg
开发语言：Python + PyQt5
支持系统：Windows / Linux / macOS

一、环境准备

1. 安装 Python

roLabelImg 需要 Python 3.x （推荐 3.6 ~ 3.8，兼容性最好）。

下载地址：https://www.python.org/downloads/
⚠️ Windows 用户 ：安装时务必勾选 "Add Python to PATH"

验证安装：

bash 复制代码

python --version
# 输出示例：Python 3.8.10

2.（推荐）创建虚拟环境

为避免依赖冲突，建议使用 Anaconda 或 venv 创建独立环境：

方式一：Anaconda

bash 复制代码

conda create -n rolabel python=3.8 -y
conda activate rolabel

方式二：venv

bash 复制代码

python -m venv rolabel_env
# Windows 激活
rolabel_env\Scripts\activate
# Linux/macOS 激活
source rolabel_env/bin/activate

二、安装依赖库

在激活的虚拟环境中，安装以下依赖：

bash 复制代码

# 安装 PyQt5（GUI 框架）
pip install PyQt5 -i https://pypi.tuna.tsinghua.edu.cn/simple

# 安装 pyqt5-tools（包含 pyrcc5 资源编译工具）
pip install pyqt5-tools -i https://pypi.tuna.tsinghua.edu.cn/simple

# 安装 lxml（XML 解析库）
pip install lxml -i https://pypi.tuna.tsinghua.edu.cn/simple

💡 使用清华镜像源 (-i https://pypi.tuna.tsinghua.edu.cn/simple) 可大幅加速下载。如果安装失败，可多尝试几次。

三、下载 roLabelImg 源码

方式一：Git 克隆（推荐）

bash 复制代码

git clone https://github.com/cgvict/roLabelImg.git
cd roLabelImg

方式二：下载 ZIP

访问 https://github.com/cgvict/roLabelImg
点击绿色 "Code" 按钮 → "Download ZIP"
解压到任意无中文、无空格 的路径下，例如 D:\tools\roLabelImg

四、编译资源文件

进入 roLabelImg 源码根目录（即包含 resources.qrc 文件的目录），执行：

bash 复制代码

cd roLabelImg   # 进入源码目录
pyrcc5 -o resources.py resources.qrc

这一步将 Qt 资源文件 resources.qrc 编译为 Python 文件 resources.py，是运行前的必要步骤。

⚠️ 如果提示 pyrcc5 不是内部命令：

说明 pyrcc5.exe 不在系统 PATH 中
找到它的路径，通常在：
- Anaconda 环境：anaconda3/envs/rolabel/Scripts/pyrcc5.exe
- venv 环境：rolabel_env/Scripts/pyrcc5.exe

将该路径添加到系统环境变量 PATH 中，或使用完整路径执行：

bash 复制代码

# 示例（Windows）
D:\anaconda3\envs\rolabel\Scripts\pyrcc5.exe -o resources.py resources.qrc

五、启动 roLabelImg

在源码根目录下运行：

bash 复制代码

python roLabelImg.py

如果一切正常，将会弹出 roLabelImg 的图形界面窗口 🎉

六、常见问题及解决方案

❌ 问题 1：`codecs` 编码错误

运行时出现类似以下报错：

复制代码

UnicodeDecodeError: 'utf-8' codec can't decode byte 0xd5 in position 0

解决方法 ：打开 roLabelImg.py，找到文件开头的编码声明，确保第一行或第二行为：

python 复制代码

# -*- coding: utf-8 -*-

同时检查文件路径中是否包含中文字符，如有请改为英文路径。

❌ 问题 2：`ModuleNotFoundError: No module named 'resources'`

原因：未执行第四步的资源编译。

解决方法：

bash 复制代码

pyrcc5 -o resources.py resources.qrc

❌ 问题 3：PyQt5 版本不兼容

解决方法：尝试安装特定版本：

bash 复制代码

pip install PyQt5==5.15.4
pip install PyQt5-tools==5.15.4.3.2

❌ 问题 4：Linux 下缺少系统依赖

bash 复制代码

sudo apt-get install pyqt5-dev-tools
sudo apt-get install python3-lxml

七、基本使用指南

启动后，常用操作如下：

操作	快捷键 / 方法
打开图片	`Ctrl + O`
打开图片目录	`Ctrl + U`
保存标注	`Ctrl + S`
创建旋转框	`Ctrl + R`
删除当前框	`Delete`
下一张图片	`D`
上一张图片	`A`
缩放	`Ctrl + +` / `Ctrl + -`

标注流程：

点击 "Open Dir" 打开图片文件夹
点击 "Change Save Dir" 设置标注文件保存路径
确认保存格式为 VOC （XML）或 YOLO（TXT）
按 Ctrl + R 绘制旋转矩形框
输入类别标签名称
按 Ctrl + S 保存，按 D 切换到下一张

八、替代方案（免安装）

如果源码安装遇到困难，也可以考虑：

预编译安装包：B站/ CSDN 上有博主提供了 Windows 一键安装包（基于 PyInstaller 打包），双击即可使用，无需配置 Python 环境。
labelImg2 ：另一个支持旋转框标注的工具，操作方式类似：
bash 复制代码
```
pip install labelImg2
```

📝 总结：核心安装流程就是 安装 Python → 安装依赖（PyQt5 + lxml）→ 下载源码 → 编译资源 → 运行，整个过程约 10 分钟。遇到问题时，优先检查 Python 版本兼容性和路径中是否有中文字符。

希望这份教程对你有帮助！如有其他问题，欢迎继续提问 😊

roLabelImg 详细安装教程