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”

验证安装：

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

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

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

方式一：Anaconda

conda create-nrolabelpython=3.8-yconda activate rolabel

方式二：venv

python-mvenv rolabel_env# Windows 激活rolabel_env\Scripts\activate# Linux/macOS 激活sourcerolabel_env/bin/activate

二、安装依赖库

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

# 安装 PyQt5（GUI 框架）pipinstallPyQt5-ihttps://pypi.tuna.tsinghua.edu.cn/simple# 安装 pyqt5-tools（包含 pyrcc5 资源编译工具）pipinstallpyqt5-tools-ihttps://pypi.tuna.tsinghua.edu.cn/simple# 安装 lxml（XML 解析库）pipinstalllxml-ihttps://pypi.tuna.tsinghua.edu.cn/simple

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

三、下载 roLabelImg 源码

方式一：Git 克隆（推荐）

gitclone https://github.com/cgvict/roLabelImg.gitcdroLabelImg

方式二：下载 ZIP

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

四、编译资源文件

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

cdroLabelImg# 进入源码目录pyrcc5-oresources.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中，或使用完整路径执行：

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

五、启动 roLabelImg

在源码根目录下运行：

python roLabelImg.py

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

六、常见问题及解决方案

❌ 问题 1：codecs编码错误

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

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

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

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

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

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

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

解决方法：

pyrcc5-oresources.py resources.qrc

❌ 问题 3：PyQt5 版本不兼容

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

pipinstallPyQt5==5.15.4 pipinstallPyQt5-tools==5.15.4.3.2

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

sudoapt-getinstallpyqt5-dev-toolssudoapt-getinstallpython3-lxml

七、基本使用指南

启动后，常用操作如下：

标注流程：

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

八、替代方案（免安装）

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

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

   pipinstalllabelImg2

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

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