4、LabelImg 实战安装与配置

工欲善其事，必先利其器。做工业缺陷检测，标注工具就是你的第一把刀。LabelImg 这工具，说简单也简单，就是个画框的。但真要在产线上跑起来，环境配置、标签文件、快捷键这些细节，一个没弄好就能卡你半天。

我记得刚带第一个项目时，团队里有个新人装了一天没装上，最后发现是 Python 版本不对。嗯，这种坑咱们今天一次性填平。

4.1 Windows 下的安装步骤

Windows 用户最多，咱们先说这个。其实就两条路：要么用 pip 装，要么用预编译包。我个人推荐 pip 方式，干净、可控。

方式一：pip 安装（推荐）

前提是你已经装好了 Python。我建议用 Python 3.8 或 3.9，别追新，3.10 以上有些依赖包还没完全跟上。

# 第一步：创建虚拟环境（强烈建议）
python -m venv labelimg_env
labelimg_env\Scripts\activate

# 第二步：安装 PyQt5 和 lxml
pip install PyQt5 lxml -i https://pypi.tuna.tsinghua.edu.cn/simple

# 第三步：安装 LabelImg
pip install labelimg -i https://pypi.tuna.tsinghua.edu.cn/simple

# 第四步：启动
labelimg

方式二：预编译包（省心但受限）

如果你不想碰命令行，可以去 GitHub Releases 页面下载 labelImg.exe。双击就能用。但说实话，我不太推荐。为啥？因为没法自定义 Python 环境，后面你要改源码或者集成其他库时会很痛苦。

4.2 Linux 下的安装步骤

Linux 下更简单，尤其是 Ubuntu。我自己的主力机就是 Ubuntu 20.04，跑 LabelImg 非常丝滑。

# Ubuntu/Debian 系
sudo apt-get install pyqt5-dev-tools
pip install labelimg

# 或者从源码编译（我偶尔这么干，为了改快捷键）
git clone https://github.com/tzutalin/labelImg.git
cd labelImg
pip install -r requirements/requirements-linux-python3.txt
make qt5py3
python labelImg.py

4.3 Python 环境配置要点

环境配置这块，说白了就是三个字：别乱装。我见过太多人把包装到系统 Python 里，最后搞得一团糟。

• 虚拟环境是底线：每个项目建一个独立的虚拟环境。用 venv 或 conda 都行，但别混用。
• 依赖版本锁定：装完后执行 pip freeze > requirements.txt，把版本号记下来。下次换机器直接 pip install -r requirements.txt 搞定。
• PyQt5 版本注意：PyQt5 5.15.x 系列最稳定。5.15.7 之后有些 API 变了，可能导致 LabelImg 界面显示异常。

# 我的标准环境配置（可直接用）
pip install PyQt5==5.15.6
pip install lxml==4.9.2
pip install labelimg==1.8.6

4.4 预定义标签文件（classes.txt）设置

这是工业缺陷检测里最容易被忽视的一步。很多人上来就手动输入标签，结果标注到一半发现标签名写错了，或者大小写不统一。你想想看，一个项目几百张图，标签不统一，后面训练模型时全是坑。

LabelImg 支持预定义标签文件，叫 classes.txt。你提前把缺陷类别写进去，标注时直接下拉选择，不会输错。

创建步骤

1. 在项目根目录下新建一个文本文件，命名为 classes.txt
2. 每行写一个缺陷类别名称，不要有空格和特殊字符
3. 保存为 UTF-8 编码（重要！否则中文标签会乱码）

# 示例：工业缺陷检测的 classes.txt
scratch
dent
crack
burr
oxidation
stain
deformation

加载方式

启动 LabelImg 后，点击左侧 「Change Save Dir」 旁边的 「Open Dir」 按钮，选择你的图片文件夹。然后在菜单栏 「View」 里勾选 「Auto Save」 和 「Display Labels」。最后，在 「File」 菜单下选择 「Open」 并选中你的 classes.txt 文件。

嗯，这里要注意：classes.txt 必须放在图片文件夹的 同级或上级目录，LabelImg 才能自动识别。我一开始没注意这个，折腾了十分钟才发现。

4.5 快捷键自定义

标注是个体力活。一张图框几十个缺陷，一天下来几百张图，手都点酸了。快捷键就是你的救命稻草。

LabelImg 默认的快捷键其实够用，但我习惯改几个，让操作更顺手。

如何修改快捷键？

LabelImg 的快捷键定义在源码的 libs/ustr.py 和 labelImg.py 里。但我不建议直接改源码，因为升级后会覆盖。

我的做法是：

1. 在项目目录下新建一个 shortcuts.txt 文件
2. 按格式写入自定义快捷键
3. 启动时用 --shortcuts 参数加载

# shortcuts.txt 示例
next_image: Space
prev_image: Shift+Space
delete_rect: Ctrl+D
zoom_in: Ctrl+Plus
zoom_out: Ctrl+Minus

# 启动命令
labelimg --shortcuts shortcuts.txt

4.6 知识结构总览

下面这张图把 LabelImg 安装配置的核心流程串起来了。你可以把它当作一个检查清单，每完成一项就打个勾。

这张图把整个流程分成了五个步骤，右侧还标注了 Windows 和 Linux 的差异点。你可以把它截图保存，装环境时对照着来，基本不会漏掉什么。