1. 问题背景与核心症结定位labelme 这个标注工具做计算机视觉数据集的朋友应该都不陌生。它轻量、开源、支持多边形、矩形、圆形、线段、点等多种标注形式导出的 JSON 可以直接转成 YOLO、COCO、VOC 等主流格式在目标检测和实例分割的数据准备环节几乎是标配。但它的安装和运行体验说实话一直不算友好尤其是版本兼容这块坑特别多。我自己最近在给一个 YOLOv8 的分割项目做数据标注重新在一台新机器上部署 labelme结果一启动就报错终端里刷出一大片AttributeError: module numpy has no attribute bool。这个报错非常典型几乎每隔一段时间就会在社区里被问一次。它的本质不是 labelme 本身写错了而是labelme 依赖的 NumPy 版本和当前环境里装的 NumPy 版本对不上。具体来说NumPy 在 1.20 版本开始对一批别名做了弃用警告到了1.24 版本直接把np.bool、np.int、np.float、np.object、np.str这些内置别名彻底移除了。而很多老版本的 labelme以及它依赖的imgviz、natsort等库代码里还在用np.bool这种写法于是新装的 NumPy 一上来就把它干掉了程序自然跑不起来。这个问题的核心症结可以归纳成一句话labelme 的版本、NumPy 的版本、Python 的版本、PyQt5 的版本四者之间存在一张隐性的兼容矩阵任意一个越界都会触发报错。所以解决思路不能只盯着np.bool这一个点而要从整体环境出发把版本组合理顺。下面这张表是我整理的常见报错与根因对照先让大家对号入座报错信息根本原因影响范围module numpy has no attribute boolNumPy ≥ 1.24 移除了np.bool别名labelme 老版本、imgviz 老版本module numpy has no attribute int同上np.int被移除同上No module named numpyNumPy 根本没装或装到了别的解释器环境隔离问题labelme 无法安装 pyqt5PyQt5 与 Python 版本不匹配Python 3.11 常见labelme error pyqt5-sipsip 版本与 PyQt5 不配套编译期或运行期module pkgutil has no attribute impimporterPython 3.12 移除了pkgutil.ImpImporter老版本 setuptools这张表基本覆盖了 90% 以上的 labelme 部署故障。接下来我会从环境设计、版本选型、实操步骤、问题排查四个维度把整个解决流程讲透。2. 环境整体设计与版本选型思路2.1 为什么强烈建议用独立虚拟环境很多人装 labelme 图省事直接pip install labelme装在系统 Python 里结果就是系统里可能已经有别的项目在用 NumPy 2.x或者 PyTorch 锁定了某个 NumPy 版本labelme 一装进去要么把别人的依赖顶掉要么自己被别人的依赖顶掉。这种依赖打架是版本不兼容问题最常见的温床。我的做法是永远给 labelme 单独开一个虚拟环境。理由很直接labelme 的依赖相对老旧它需要的是偏保守的 NumPy 和 PyQt5 版本深度学习训练环境PyTorch/TensorFlow往往需要较新的 NumPy两者混在一起迟早出事而且排查起来极其痛苦。用 conda 或者 venv 都行。conda 的好处是能同时管理 Python 版本对 labelme 这种对 Python 版本敏感的工具更友好。我个人的习惯是用 conda 建一个 Python 3.9 或 3.10 的环境这两个版本是目前兼容性最好的甜点区。2.2 版本兼容矩阵一张表说清楚labelme 的版本迭代比较快不同版本对依赖的要求差别很大。我实测下来比较稳的组合是下面这几种labelme 版本Python 版本NumPy 版本PyQt5 版本备注5.8.33.9 / 3.10 1.245.15.x当前推荐功能完整5.4.x3.8 / 3.9 1.245.15.x老项目兼容5.0.x3.7 / 3.8 1.205.15.x很老不推荐新装4.x3.6 / 3.7 1.205.12.x仅维护老项目关键结论只要把 NumPy 锁在 1.24 以下np.bool这类报错基本就消失了。但光锁 NumPy 还不够因为 labelme 5.8.3 本身对 PyQt5 也有要求Python 3.11 及以上装 PyQt5 经常编译失败所以 Python 版本也要往下压一压。2.3 为什么不用降级 NumPy一招走天下网上很多帖子给的方案是把 NumPy 降到 1.23 就好了。这招确实能解决np.bool报错但它有两个隐患第一如果你这个环境里还装了别的库比如新版 OpenCV、新版 scikit-image它们可能反过来要求 NumPy ≥ 1.24你一降级别的库又崩了。这就是典型的按下葫芦浮起瓢。第二降级 NumPy 只是治标。labelme 报np.bool只是因为它代码里用了老别名但如果你装的是很老的 labelme可能还有别的兼容问题在等着你。所以更彻底的做法是升级 labelme 到较新版本 锁定 NumPy 到兼容区间双管齐下。2.4 镜像源的选择国内装这些包直连官方源经常卡在Installing backend dependencies那一步或者下载到一半超时。我的习惯是全程走清华镜像pip install labelme -i https://pypi.tuna.tsinghua.edu.cn/simple如果 conda 装包慢也可以配置 conda 的清华源。这一步看似小事但能省掉大量卡住不动的等待时间尤其是装 PyQt5 这种带二进制的大包时镜像源几乎是刚需。3. 核心细节解析与实操要点3.1 从零搭建完整可复现的安装流程下面这套流程是我在 Windows 和 Linux 上都验证过的直接抄作业即可。以 conda 为例# 1. 创建独立环境Python 锁 3.9 conda create -n labelme_env python3.9 -y # 2. 激活环境 conda activate labelme_env # 3. 先装 NumPy锁在 1.23.51.24 以下都行 pip install numpy1.24 -i https://pypi.tuna.tsinghua.edu.cn/simple # 4. 装 labelme指定较新版本 pip install labelme5.8.3 -i https://pypi.tuna.tsinghua.edu.cn/simple # 5. 验证 labelme --version这里有几个细节值得展开说。为什么先装 NumPy 再装 labelme因为 labelme 安装时会自动拉取依赖如果它拉的是最新版 NumPy2.x那np.bool报错就埋下了。先手动把 NumPy 钉死在 1.23.5pip 在装 labelme 时看到 NumPy 已满足要求就不会再动它。这是一种先占坑的策略。为什么指定 labelme5.8.35.8.3 是相对成熟的一个版本修复了不少老版本的兼容问题同时对 NumPy 的要求还没那么激进。如果你不指定版本pip 可能给你装最新的而最新版有时会引入新的依赖变动反而不好控制。验证环节不能省。labelme --version能正常输出版本号说明基本环境通了。如果这一步就报No module named numpy那说明你的 pip 和 python 不是同一个解释器这是另一个高频坑后面会专门讲。3.2 已经装错了怎么办修复而非重装如果你已经装好了一运行就报np.bool不用整个环境删掉重来按下面步骤修复即可# 查看当前 NumPy 版本 pip show numpy # 如果版本 1.24降级 pip install numpy1.23.5 -i https://pypi.tuna.tsinghua.edu.cn/simple # 顺便把 imgviz 也检查一下它是 labelme 的依赖老版本也用 np.bool pip install --upgrade imgviz -i https://pypi.tuna.tsinghua.edu.cn/simple这里要特别提一下imgviz。很多人只盯着 NumPy降完 NumPy 发现还报np.bool就是因为 imgviz 这个库自己代码里也用了老别名。imgviz 是 labelme 作者写的可视化库labelme 强依赖它。新版 imgviz 已经修掉了这个问题所以顺手升级一下能避免二次踩坑。3.3 PyQt5 安装失败的应对Python 3.11 及以上装 PyQt5经常卡在编译或者直接报labelme 无法安装 pyqt5。原因是 PyQt5 的预编译 wheel 对 Python 版本有窗口期太新的 Python 还没对应的 wheelpip 就尝试从源码编译而源码编译又需要 Qt 开发环境普通机器根本没有。解决办法有两个首选把 Python 降到 3.9 或 3.10这两个版本 PyQt5 的 wheel 齐全一条命令就装好次选如果非要用高版本 Python试试pip install PyQt55.15.9指定一个较新的 PyQt5 版本它可能已经提供了对应 wheel。如果报的是labelme error pyqt5-sip那是 sip 这个绑定层版本不配套。直接pip install --upgrade pyqt5-sip -i https://pypi.tuna.tsinghua.edu.cn/simplesip 是 PyQt5 和 C Qt 之间的桥版本必须和 PyQt5 对齐升级到最新一般能解决。3.4 解释器错位为什么 PyCharm 里有 NumPy 却显示没有这是另一个高频问题热词里也出现了——为什么 pycharm 有 numpy 库但是一直显示没有。根因是PyCharm 项目解释器和你在终端里 pip 装包的解释器不是同一个。你在系统终端pip install numpy装到了系统 Python但 PyCharm 项目用的是 conda 环境或者另一个 venv那个环境里没有 NumPy自然报ModuleNotFoundError: No module named numpy。排查方法在 PyCharm 里打开File - Settings - Project - Python Interpreter看清楚当前用的是哪个解释器路径在终端里执行which pythonLinux/Mac或where pythonWindows对比路径是否一致如果不一致要么在 PyCharm 里切换到正确的解释器要么用那个解释器对应的 pip 重新装包。最稳的做法是在 PyCharm 的 Terminal 里装包因为 PyCharm 的 Terminal 默认激活的就是当前项目解释器这样装出来的包一定对得上。4. 实操过程与核心环节实现4.1 完整部署实录从裸机到能标注我把整个部署过程按时间线记录一遍包含每一步的实际输出和判断依据方便大家对照。第一步确认系统 Python 情况。执行python --version我这边显示 3.11.5。这个版本对 labelme 来说偏新PyQt5 可能装不上所以我决定用 conda 建一个 3.9 的环境不动系统 Python。第二步创建 conda 环境。执行conda create -n labelme_env python3.9 -y大约 30 秒完成。激活后python --version显示 3.9.18符合预期。第三步装 NumPy。执行pip install numpy1.24 -i https://pypi.tuna.tsinghua.edu.cn/simple实际装的是 1.23.5。这里我特意用1.24而不是写死 1.23.5是为了让 pip 自己选一个满足条件的最高版本兼容性更好。第四步装 labelme。执行pip install labelme5.8.3 -i https://pypi.tuna.tsinghua.edu.cn/simple。这一步会拉一堆依赖PyQt5、imgviz、natsort、Pillow、PyYAML 等。因为 NumPy 已经占好坑pip 不会动它。整个过程大约 2 分钟走镜像源很顺畅。第五步验证。执行labelme --version输出5.8.3。再执行labelmeGUI 正常弹出没有报错。到这一步环境就通了。第六步实际标注测试。打开一张图画几个多边形保存 JSON确认导出正常。这一步是为了验证不只是能启动功能也完整。4.2 参数选择背后的计算逻辑有人可能会问为什么 NumPy 要锁在 1.24 以下而不是 1.23 或者 1.22这里有个版本演进的逻辑NumPy 1.20开始对np.bool等别名发 DeprecationWarning但还能用NumPy 1.24正式移除这些别名用了就报 AttributeErrorNumPy 2.0进一步大改很多老库直接不兼容。所以1.24 是一条硬分界线。锁在 1.24 以下就能保证np.bool还能用。而在 1.24 以下的范围里1.23.x 是最后一个稳定小版本功能最全、bug 最少所以我选 1.23.5。同理Python 选 3.9 而不是 3.8是因为 3.9 对 PyQt5 5.15.x 的支持最完整同时又不至于太老导致别的工具链不认。3.10 也可以但 3.9 的生态兼容性更广一些。4.3 用 requirements.txt 固化环境环境配好之后一定要导出依赖清单方便以后复现或者迁移到别的机器pip freeze requirements.txt下次在新机器上直接pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple这样版本组合就被完整锁定了不会再出现这台机器能跑那台机器报错的情况。我强烈建议把这份 requirements.txt 和项目代码一起提交到版本库团队协作时能省掉大量沟通成本。4.4 labelme 标注到 YOLOv8 的衔接既然热词里提到了labelme标注用于yolov8我顺带说一下衔接环节。labelme 导出的是 JSON 格式YOLOv8 需要的是 txt 格式每行class x_center y_center width height归一化到 0-1。中间需要一个转换脚本。转换的核心逻辑是读取 JSON 里的shapes数组取出每个多边形的点坐标计算外接矩形再归一化。如果是分割任务则直接保留多边形点集转成 YOLOv8-seg 需要的格式。这一步虽然不属于版本兼容范畴但很多人是在装好 labelme 之后紧接着就要做转换所以提前知道这个衔接点能少走弯路。5. 常见问题与排查技巧实录5.1 高频问题速查表下面这张表是我在实际部署中反复遇到并验证过解决方案的清单建议收藏现象排查方向解决命令np.bool报错NumPy ≥ 1.24pip install numpy1.24np.int报错同上同上No module named numpy解释器错位检查 pip 与 python 是否同源PyQt5 装不上Python 版本过高降到 3.9/3.10pyqt5-sip报错sip 版本不配套pip install --upgrade pyqt5-sip卡在 backend dependencies网络问题换清华镜像源pkgutil.impimporter报错Python 3.12 老 setuptools升级 setuptoolsGUI 启动闪退显卡/显示驱动检查 Qt 平台插件5.2 独家避坑技巧技巧一先看报错栈的最后一行。Python 的报错栈很长但真正有用的信息往往在最后一行。AttributeError: module numpy has no attribute bool这种一眼就能定位到是 NumPy 版本问题。不要被前面几十行吓到。技巧二用pip show而不是pip list定位单个包。pip list输出一大堆找起来费劲。pip show numpy直接告诉你版本、安装路径、依赖关系排查时效率高得多。技巧三环境隔离是万能药。90% 的版本冲突根源都是多个项目共用一个环境。养成一个项目一个环境的习惯能避免绝大多数兼容问题。conda 的conda env list和conda activate用熟了管理起来并不麻烦。技巧四装包顺序有讲究。先装约束性强的包NumPy再装依赖它的包labelme让 pip 在已有约束下解析依赖比反过来装要稳。这个思路对所有有版本冲突的库都适用。技巧五遇到pkgutil.impimporter报错先升级 setuptools。这个报错是 Python 3.12 移除了pkgutil.ImpImporter而老版本 setuptools 还在用它。执行pip install --upgrade setuptools基本能解决。如果还不行说明某个包太老需要单独升级那个包。5.3 一个容易被忽略的坑中文路径labelme 在 Windows 上如果图片路径或者保存路径包含中文有时会出现保存失败或者乱码。这不是版本兼容问题但经常和版本问题混在一起被误判。我的建议是标注数据全程用英文路径省心。如果非要用中文路径确保系统区域设置里的非 Unicode 程序语言设为中文能缓解一部分问题。5.4 关于 NumPy 2.x 的额外提醒NumPy 2.0 是一次大版本升级ABI 层面有破坏性变更。很多用 C 扩展编译的库比如老版本 OpenCV、老版本 scipy在 NumPy 2.x 下会直接崩。如果你环境里同时有这些库强烈建议把 NumPy 锁在 1.x不要轻易升到 2.x。labelme 本身对 NumPy 2.x 的支持也还在完善中稳妥起见1.23.5 是目前最省心的选择。6. 版本锁定与环境复现的长期策略6.1 把环境当成代码来管理版本不兼容问题的本质是环境状态没有被显式记录。今天装好了明天手滑升级一个包可能又崩了。所以长期来看要把环境当成代码一样管理用requirements.txt或environment.yml锁定所有依赖版本把这份文件提交到 Git每次环境变更后重新导出并提交新机器部署时严格按文件安装不手动pip install单个包。这套流程看起来麻烦但比起每次出问题重新排查长期成本低得多。6.2 conda 环境导出与复现如果用的是 conda导出方式略有不同# 导出完整环境包含 Python 版本和所有依赖 conda env export environment.yml # 在新机器上复现 conda env create -f environment.yml注意conda env export默认会带上平台相关的 build 信息跨平台复现时可能出问题。可以用conda env export --no-builds去掉 build 号兼容性更好。6.3 定期检查依赖健康度环境用久了依赖会慢慢腐烂。我习惯每隔一两个月做一次检查# 检查哪些包有新版本 pip list --outdated # 检查依赖冲突 pip checkpip check会告诉你哪些包的依赖关系被破坏了是发现潜在冲突的好工具。但注意不要看到有新版本就无脑升级尤其是 NumPy、PyQt5 这种核心依赖升级前先确认 labelme 是否兼容。6.4 团队协作时的环境统一如果是团队一起做标注环境不统一会导致我这边能跑你那边报错。解决办法是统一用同一份 requirements.txt统一 Python 版本写进文档统一镜像源配置新成员入职第一件事就是按文档配环境配完跑一遍验证脚本。验证脚本可以很简单就是启动 labelme、打开一张测试图、画一个框、保存、确认 JSON 生成。跑通了环境就没问题。7. 从报错到掌控我的几点实际体会折腾 labelme 的版本兼容问题前前后后踩了不少坑也总结出一些超出照着命令敲层面的体会。第一报错信息是最好的老师。np.bool这个报错如果你去查 NumPy 的 release notes会发现 1.24 的移除清单里写得清清楚楚。养成看官方 changelog 的习惯比在论坛里翻帖子高效得多。很多玄学问题官方文档里其实早有答案。第二版本兼容问题的解法是约束而不是追新。很多人下意识觉得装最新版就对了但在工具链场景里最新版往往意味着最大的不确定性。labelme 这种依赖链较长的工具稳定压倒一切。锁定一个验证过的版本组合比每次追新要省心得多。第三环境隔离要趁早。我早期图省事所有东西装一个环境结果就是每次装新工具都提心吊胆生怕把之前的搞崩。后来养成一个项目一个环境的习惯世界清净了。这个习惯的收益远超它带来的那点管理成本。第四把解决方案文档化。每次解决一个兼容问题我都会在项目的 README 或者内部 wiki 里记一笔什么报错、什么原因、怎么解决。下次再遇到直接查自己的记录不用重新搜索。这份积累时间越长越值钱。最后分享一个小技巧如果你不确定某个包该装什么版本可以去它的 GitHub releases 页面看发布时间和对应的依赖要求或者直接看它的setup.py/pyproject.toml里的install_requires。这比盲目试版本要快得多。labelme 的依赖要求就写在它的setup.py里装之前扫一眼能避开很多坑。
