简介面向图像分割与标注初学者及需要快速上手 Labelme 的计算机视觉从业者这份文档围绕 Labelme 的安装与使用展开重点解决 Anaconda 环境准备、虚拟环境创建、工具启动及标注结果转换等常见问题。资源包仅含 1 个 docx 文件体积约 14KB篇幅精简便于随查随用内容按安装与使用两部分组织覆盖 Python 2/3 两种环境下的 conda 与 pip 指令、pyqt/pyqt5 依赖安装、labelme 环境激活以及通过 json_to_dataset 将标注文件转为可视化结果的操作说明。已有 15266 人学习适合作为入门阶段的步骤参考和命令速查材料也能帮助读者减少环境配置与首次标注时的试错成本快速完成从工具安装到结果查看的完整流程。1. 从一台只能开机的 Windows 说起labelme 装不上多半不是 labelme 的问题第一次在同学的笔记本上装 labelme我把pip install labelme敲进去看着进度条一路走完以为三分钟就能收工。结果命令行里一敲labelme窗口闪一下就退终端里只留下一行 Qt platform plugin 之类的报错。回头翻才发现真正出问题的不是 labelme 本身而是它依赖的基础环境Python 版本、PyQt 二进制、conda 环境的激活方式只要哪一环对不上界面就起不来。图像分割标注这活儿标一张图几十秒装环境却能耗掉一下午这就是我后来坚持把 labelme 装进独立 conda 环境、并且每次装完都先跑一遍 JSON 转换脚本的原因。这套流程适合刚接触图像标注的算法同学、要批量整理数据集的数据工程岗也适合那种「装过一次但换台机器就全忘」的人。下面按我实际装机的顺序从 Anaconda 一路写到python labelme_json_to_dataset能稳定出图为止。2. 装 Anaconda 之前先定 Python版本线、安装选项与环境盘点2.1 为什么不把 labelme 直接装进系统 Pythonlabelme 表面上是「一个 pip 包」实际上底层依赖一层图形栈PyQtQt 的 Python 绑定、numpy、Pillow外加处理 JSON 的一堆小包。用pip install labelme直接装进系统 Python这些东西会全部塞进全局 site-packages。平时看不出问题等到你哪天为了跑另一个项目升级了 numpy 或换了 Qt 版本labelme 就会毫无征兆地起不来而且报错指向的是 Qt 插件加载失败根本不会告诉你真正的原因是某个依赖被换掉了。虚拟环境就是这一步的补救办法。Python 自带的venv也能隔离包但它只管 Python 包管不了 Qt 这类带本地二进制的依赖conda 能把这部分一起锁进环境里所以原始教程里用的是conda create而不是python -m venv。这个选择是对的环境一旦建好后面无论怎么折腾别的项目labelme 这套环境都能保持原样坏了直接把整个环境删掉重建比在系统 Python 里一个个卸包快得多。另外要提前想清楚走哪条版本线。教程里给了 Python 2.7 和 Python 3.6 两条命令分别对应老代码和新项目。Python 2.7 早已停止维护新装的机器没必要为了 labelme 单独选它但如果你手里的标注脚本、转换脚本是好几年前写的 py2 代码直接搬到 3.x 上可能连 print 语法都过不去那就老老实实留一条 2.7 的环境。我的建议是主力环境用 Python 3老项目需要时再建一个 2.7 的并存两个环境名不要重名比如labelme和labelme27。2.2 Anaconda 安装包的选择与安装时该勾什么下载入口就是 Anaconda 官方下载页页面上会按操作系统给出对应的安装包。有两个地方容易选错一是位数现在的机器基本都是 64 位选 64-bit installer别下意识点 32 位二是版本安装包本身已经绑定了 Python 解释器版本但这不是决定性的因为后面建环境时可以用python3.6这种参数指定版本conda 会自己去拉对应的解释器。所以安装包不用纠结到小数点选一个和你目标版本接近的就行。安装路径这件事值得单独说。不要装在C:\Program Files下面那个目录写入需要管理员权限后面 conda 装包、pip 装包都容易因为权限失败而且失败信息往往只有一句「Permission denied」不看日志根本定位不到。我一般统一放在D:\anaconda3这类全英文、无空格的短路径下。中文路径和空格是另一个经典问题conda 在某些版本上处理带空格路径时会截断装到一半报找不到文件排查起来非常费劲。安装向导里有两个勾选项Add Anaconda3 to my PATH environment variable默认不勾我也建议保持不勾。勾了之后系统 PATH 里会多出一串 conda 的目录和你机器上已有的 Python 抢优先级python命令到底指向谁就说不清了。正确做法是用开始菜单里的 Anaconda Prompt它启动时会自动帮你把环境变量配好。Register Anaconda3 as my default Python 3.x这个可以勾影响不大主要是让某些安装程序识别到 Python 位置。装完之后从开始菜单打开 Anaconda Prompt或者普通 cmd 也行前提是安装时勾了 PATH先做一轮基础检查:: 确认 conda 命令在不在 PATH 里会输出 conda 的可执行文件路径 where conda :: 看版本号能打印出来说明命令可用 conda --version :: 列出当前所有环境刚装完通常只有 base conda info --envswhere conda的作用是定位命令来源输出一般是D:\anaconda3\Scripts\conda.exe和D:\anaconda3\condabin\conda.bat两条。如果这条命令报「不是内部或外部命令」说明安装时没勾 PATH也没关系改用 Anaconda Prompt 打开终端即可不用回去重装。conda info --envs的输出里当前激活的环境前面会有一个星号刚装完星号在base上后面每建一个新环境这里就会多一行。2.3 终端编码与权限两个容易被忽略的前置条件Windows 的 cmd 默认代码页是 GBK而 conda 和 pip 的部分输出是 UTF-8。这个差异平时不显眼但在装包失败时报错信息里的中文或特殊字符会变成一堆乱码你想搜都搜不了。养成习惯装环境前先切一次编码:: 把当前 cmd 窗口切到 UTF-8只对当前窗口生效关掉就恢复 chcp 65001这条命令不改系统设置只影响当前窗口所以不用担心污染别的终端。切完之后 conda 的进度条和错误信息都能正常显示遇到问题直接复制报错去搜效率差好几倍。权限方面如果安装 Anaconda 时选的是「Just Me」那么后续所有 conda 操作都在用户目录下不需要管理员。如果选了「All Users」某些包会尝试写入公共目录普通权限下会失败。遇到那种「装到一半突然停在某个包上不动最后报权限错误」的情况先确认自己是不是在非管理员窗口里跑 All Users 安装的环境这属于配置层面的问题重装一遍能省下大量排查时间。3. 建 labelme 虚拟环境python2.7 与 python3.6 两条命令路线3.1 conda create --namelabelme python3.6 这条命令到底做了什么原文给的第一条命令就是建环境看起来只有一行实际上 conda 在背后做了好几件事解析python3.6这个约束从配置的 channel 里找出满足条件的解释器连同它的标准库、pip、setuptools 一起下载然后解压到一个独立的目录通常在 Anaconda 安装目录的envs\labelme下最后在环境里注册好 pip。整个过程不会碰系统 Python这就是环境隔离的意义。:: 创建名为 labelme 的环境并把解释器版本钉死在 3.6 :: --name 也可以简写成 -n-y 表示所有确认提示自动回答 yes conda create --namelabelme python3.6 -y :: 建完之后看一眼新环境应该出现在列表里 conda info --envs参数拆开看--namelabelme里的labelme是这个环境的名字后面所有激活、删除操作都靠它定位所以起名要短、要有辨识度别用test、env1这种过两天就忘的名字。python3.6是版本约束等号表示精确匹配小版本如果你想让它自己挑一个兼容的最新小版本可以写成python3.6conda 会在 3.6.x 里选如果想限定到具体补丁版本就得写python3.6.8。-y是跳过交互确认脚本化安装时必带手动装的话去掉也无所谓。这里有个新手常犯的错误建完环境不激活就去pip install。这时候 pip 装的是 base 环境里的包里不是新环境。判断方法很简单看命令行提示符前缀有没有变成(labelme)有就说明激活成功了。3.2 Python 3 路线activate labelme 搭配 pyqt5激活命令在不同 shell 下写法不一样这是原文里最容易让人困惑的地方。原文写的是source activate labelme这个写法来自 Linux/macOS 的 bash 环境在 Windows 的 cmd 里正确写法是activate labelme。如果你用的是 PowerShell则是conda activate labelme新版本 conda 推荐统一用这个。:: 进入 labelme 环境成功后提示符前面会出现 (labelme) activate labelme :: 确认 python 指向的是环境内的解释器而不是系统那个 where python python --version :: 先装图形依赖再装 labelme 本体 pip install pyqt5 -i https://pypi.tuna.tsinghua.edu.cn/simplewhere python这一步非常关键。装过 Anaconda 又装过官方 Python 的机器上PATH 里可能有好几个 python.exe如果输出里第一个路径不在envs\labelme下面说明激活没生效后面装什么都白搭。正常情况下应该看到类似D:\anaconda3\envs\labelme\python.exe的路径。pip install pyqt5后面挂的-i参数是指定包索引源。PyQt5 的 wheel 包体积不小用默认源在国内网络下经常卡在百分之几不动换成常用的国内镜像能快很多。这个参数只对当前这条命令生效如果想永久改可以用pip config set写进配置后面第 3.4 节会说。3.3 Python 2 路线conda install pyqt 与版本对齐Python 2.7 那条路线除了版本号不同装 Qt 依赖的方式也不一样。原文用的是conda install pyqt而不是 pip这是有道理的conda 源里的 pyqt 包是预编译好的能自动匹配当前环境里的 Python 版本和系统架构省去了自己找 wheel 的麻烦。:: Python 2.7 路线环境名建议加后缀区分避免和 3.x 那条重名 conda create --namelabelme27 python2.7 -y :: 激活cmd 下用 activate不要照抄 source activate activate labelme27 :: 用 conda 装 Qt 绑定让它自己解决版本匹配 conda install pyqt -y :: 最后装 labelme 本体 pip install labelme这里有个细节conda install pyqt装的具体是哪个大版本取决于你配置的 channel 和当时的包状态不同时间、不同机器装出来可能不一样。所以在 py2 环境里不建议再手动pip install pyqt5去覆盖两套包管理混着装同一个库很容易出现 DLL 冲突症状就是启动时窗口闪退。我的习惯是Qt 这一层交给 condalabelme 本体交给 pip职责分清楚出问题也好定位是哪一层的事。3.4 两条路线怎么选一张对照表对比项Python 2.7 路线Python 3.6 路线建环境命令conda create --namelabelme27 python2.7 -yconda create --namelabelme python3.6 -y激活方式Windows cmdactivate labelme27activate labelmeQt 依赖安装方式conda install pyqtpip install pyqt5适用场景老标注脚本、历史数据集转换代码新项目、主流深度学习框架配套维护状态已停止官方维护仅作兼容仍可正常获取包选择逻辑很简单新机器、新项目一律走 Python 3只有在接手一份跑了好几年的标注工程脚本里到处是 py2 语法时才需要额外建一个 2.7 环境。两个环境可以共存切换时只要activate对应的名字就行互不干扰。3.5 给环境单独配 pip 源省掉每次敲 -i如果你不想每条 pip 命令后面都挂一长串-i参数可以在激活环境后写一次配置。注意这一步要在激活环境之后执行配置才会写进这个环境自己的 pip 配置文件里不会影响 base。:: 给当前环境设置默认索引源 pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple :: 顺便把超时时间拉长PyQt 这类大包下载慢时不容易断 pip config set global.timeout 120 :: 确认配置写进去了 pip config listglobal.index-url改的是包的下载来源global.timeout单位是秒默认 15 秒对大包来说偏短网络一抖就中断重来一次又要从头下。设成 120 秒之后装 PyQt5 的成功率会明显高一些。pip config list会把当前生效的所有配置项列出来如果输出是空的说明你不在虚拟环境里或者写到了别的位置。4. 装 labelme 本体pip install 前后的依赖顺序4.1 为什么必须先装 pyqt 再装 labelmelabelme 启动的第一件事就是初始化 Qt 应用对象也就是说它对 Qt 的依赖是硬性的、在 import 阶段就会触发。如果你先pip install labelmepip 会按照包元数据里的依赖声明去解析但 PyQt 这类带 C 扩展的包在不同 Python 版本上能匹配到的 wheel 不一样解析出来的版本未必能在你的机器上正常加载。表现出来就是装的时候一路绿灯一运行就报Could not find the Qt platform plugin windows。先手动把 PyQt 装好等于提前把最容易出问题的那一环固定下来。装 labelme 时 pip 发现依赖已满足就会跳过不会再去动它。这个顺序在原始教程里也是这么写的先 pyqt5/pyqt后 labelme这不是随手排的。4.2 pip install labelme 的参数与版本回退:: 确认还在 labelme 环境里提示符前缀必须是 (labelme) activate labelme :: 装 labelme 本体 pip install labelme :: 装完看看到底装了什么版本后面要复现环境时靠它 pip show labelmepip show labelme的输出里Version这一行就是实际装上的版本号Location是安装路径正常情况下应该指向envs\labelme\Lib\site-packages。把版本号记下来等你换机器或者帮别人装的时候可以直接用pip install labelme版本号复现同样的组合。版本号以你机器上实际输出的为准不要照抄教程里别人的数字不同时期装出来的可能差好几个大版本。万一新版装完起不来回退的做法是先卸再装指定版本:: 卸载当前版本 pip uninstall labelme -y :: 装一个你验证过能用的版本把 x.y.z 换成 pip show 里记下的数字 pip install labelmex.y.z-y同样是跳过确认。回退的时候不用管 PyQt它没被动过卸 labelme 不会连带卸依赖这是 pip 的默认行为要连带卸依赖得额外装工具。这也正是前面强调「先装 PyQt」的好处回退成本只在一个包上。4.3 装完的三条自检命令装完不要急着开界面先在命令行里做三项检查能在几秒内排除掉大部分低级问题。:: 第一项包在不在findstr 是 Windows 下的过滤命令等价于 grep pip list | findstr /i labelme :: 第二项路径对不对Location 必须指向 envs\labelme 下面 pip show labelme :: 第三项能不能 import能不能打印出版本和路径 python -c import labelme, sys; print(labelme.__file__); print(sys.version)第一条确认包装上了第二条确认装在了正确的环境里而不是 base第三条确认 Python 解释器能真正加载这个模块。第三条最有价值如果 import 就报错说明依赖有问题这时候开界面必然是闪退如果 import 通过但界面起不来问题就缩小到 Qt 那一层排查范围小了一大半。有一点要注意第三条命令里的分号是 Python 语句分隔符整段用双引号包住在 cmd 里可以直接执行。如果你的路径里有特殊字符可能会被命令行解释掉那就把这段存成一个临时的 .py 文件再跑稳妥一些。5. 避坑与排查五条踩过的坑按现象对号入座5.1 现象输入 labelme 后窗口闪一下就退报 Qt platform plugin windows原因通常有两个。一是 PyQt5 装到了 base 环境而不是 labelme 环境激活状态下where python却指向系统解释器二是 PyQt5 的版本和当前 Python 的小版本不匹配比如在 3.6 上装了一个只提供 3.9 wheel 的版本pip 会退回源码编译编译出来的扩展加载失败。解决顺序是先把环境确认一遍activate labelme然后where python确认第一条路径在envs\labelme下再pip show pyqt5看 Location 是不是同一个环境。两边都在环境里之后执行pip uninstall pyqt5 -y再重新pip install pyqt5让它针对当前解释器重新解析 wheel。如果重装还是失败说明这个 Python 版本没有可用的预编译包换成教程里的 3.6 重新建环境比继续修更快。5.2 现象activate labelme 提示「不是内部或外部命令」原因是你用的 cmd 没有经过 conda 初始化PATH 里没有 conda 的相关目录。安装 Anaconda 时如果没勾「Add to PATH」普通 cmd 就是这样。解决办法有两个任选其一。短期方案是从开始菜单打开 Anaconda Prompt它自带环境变量activate labelme直接可用。长期方案是在普通 cmd 里执行一次conda init cmd.exe然后关掉窗口重新打开让初始化脚本生效。执行完conda init之后你的 cmd 启动时会自动跑一段 conda 的钩子激活命令就正常了。注意conda init会修改你的终端配置文件如果不喜欢这种改动就老老实实用 Anaconda Prompt别去动它。5.3 现象pip install 卡在下载环节进度条长时间不动或直接超时原因是默认包索引在境外PyQt5 的 wheel 包动辄几十兆网络稍微抖一下就断。另外如果你在同一个环境里同时用 conda 和 pip 装包conda 的解析器有时会和 pip 的缓存打架表现也是卡住。解决做法先换源用-i参数或者第 3.5 节的pip config set再把超时拉长到 120 秒最后把 PyQt5 和 labelme 分成两条命令装别写成一条这样中断了只需要重跑失败的那半截。如果换了源还是卡试着清一下 pip 缓存pip cache purge再装缓存里存了半个损坏的包时重试多少次都是同样的错。5.4 现象python labelme_json_to_dataset 报找不到模块或者找不到 json 文件这个命令必须在激活了 labelme 环境的终端里执行而且工作目录要能看到那个 json。常见情况是图形界面是在 Anaconda Prompt 里开的转换命令却跑到另一个普通 cmd 窗口里敲那个窗口里根本没有 labelme 这个模块。另一个容易忽略的点是路径。文件名里带空格、带中文或者你只写了文件名但当前目录不在 json 所在位置都会报「系统找不到指定的文件」。稳妥的写法是先cd到 json 所在目录再用相对路径执行实在不想切目录就直接写绝对路径把整个路径用双引号包起来。转换前用dir *.json确认一下文件确实在这里比对着报错猜要有用得多。5.5 现象装完之后 base 环境变臃肿或者别的项目开始报依赖冲突原因基本只有一个某次pip install忘了先激活环境包全进了 base。base 是 conda 的根环境很多工具的入口都挂在这里一旦被污染修起来比重装还麻烦。排查方法conda activate base之后执行pip list看里面有没有 labelme、pyqt5 这些本该在虚拟环境里的包。有的话在 base 里pip uninstall掉它们然后回到 labelme 环境重新装一遍。为了以后不再犯我的做法是把「激活」和「安装」写成连续的两条命令贴在一起中间不给自己插入别的操作的机会——听起来很傻但确实有效。6. 装完怎么验证界面起得来JSON 还得能出图环境装完不等于这套流程跑通。labelme 有两半功能一半是图形界面里画多边形、打标签另一半是把保存出来的 JSON 转成训练能用的掩码图。只验证前半截很可能到批量处理数据集时才发现转换脚本跑不起来那时候数据已经标了一半返工成本更高。我一般按下面三步走完全程不超过五分钟。第一步激活环境并启动界面。这一步验证的是 Qt 那一层有没有装对:: 进入环境并启动图形界面 activate labelme labelme窗口能正常弹出、能通过 File 菜单打开一张本地图片就说明 GUI 依赖没问题。如果窗口闪退回到 5.1 节排查不要在没起界面的情况下继续往下走。第二步随便标一个小目标并保存。在图片上点 Create Polygons沿物体边缘画一圈输入标签名然后 CtrlS 保存。保存时会让你选路径文件名保持默认的 .json 后缀即可。这一步的目的是拿到一个真实的 JSON 样本后面转换要用。第三步把 JSON 转成可视化结果。这一步验证的是整条数据处理链路:: 先确认在 json 所在目录避免路径问题 cd /d D:\work\label_test :: 执行转换不加 -o 时会在同级生成一个同名输出目录 python labelme_json_to_dataset 001.json :: 转换完看输出目录里有什么 dir 001_jsonlabelme_json_to_dataset是 labelme 安装时一起装进来的命令行工具不用单独下载。参数上第一个位置参数就是 JSON 文件路径-o可以指定输出目录不指定时默认在 JSON 同级建一个以文件名命名的文件夹。转换完成后输出目录里通常会有这么几个文件文件名内容img.png原始图像供后续对齐使用label.png标注生成的掩码图像素值对应类别编号label_names.txt类别名称列表顺序和掩码里的编号对应label_viz.png叠加了彩色掩码的可视化图人眼检查用重点看label_viz.png。这张图能打开、能看到你标的那块区域被涂上了颜色就说明从标注到转换整条链路是通的。如果label.png是全黑的先别怀疑环境八成是画多边形时没闭合或者标签名没填回去重新标一个再转一次。提示转换命令建议在激活 labelme 环境的同一个终端里执行跨终端操作是这类「模块找不到」报错最常见的来源。从那以后我每次装完 labelme 都强制走一遍这三步哪怕只是帮别人在临时机器上装一个也不会跳过 JSON 转换这一步——界面能开只是看起来能用掩码能出来才算真的跑通。希望这套流程能帮你少熬一个下午。本文还有配套的精品资源点击获取
