先交代一下背景。做计算机视觉项目不管你是搞目标检测、语义分割还是实例分割永远绕不开数据标注这一步。而 Labelme 作为一款开源图像标注工具在 Windows 系统下的安装和使用可以说是每个新手必过的一道坎。我见过太多人在第一步就卡住要么 PyQt5 装不上要么装上了不知道怎么画多边形要么标完一堆 JSON 文件却不知道下一步该怎么办。这篇文章我会把从零开始的完整流程拆开揉碎逐步演示安装、启动、标注和格式转换帮你在 Windows 下把整个标注链路彻底跑通。文章面向刚接触图像标注的算法工程师、数据标注新人也适合准备做语义分割或实例分割项目、想自己生成训练数据集的读者。按照我平时做项目实际走的顺序来写尽量把每一步背后的原理和注意事项也讲清楚不希望你只是照着命令敲一遍。1. 项目背景与整体思路为什么数据标注绕不开 Labelme1.1 Labelme 是什么能解决什么问题Labelme 是基于 Python 开发的开源图像标注工具最初由麻省理工学院的计算机科学和人工智能实验室发布。它最核心的能力是支持多边形标注也就是你可以沿着目标物体边缘打点闭合后得到一个不规则区域正好对应语义分割和实例分割任务里的像素级标注需求。以前大家做目标检测用 LabelImg 画矩形框就足够了但一旦模型需要输出轮廓、区分每一个实例矩形框就远远不够Labelme 的多边形标注能力恰好填补这个缺口。除了多边形它还支持矩形框、圆形、线条、点以及图像分类标签。换句话说从目标检测到关键点检测、从边缘分割到图像分类一个工具基本都能覆盖。我平时做工业质检、遥感地物识别、医学影像辅助诊断这类项目时第一步永远是把图像整理好然后用 Labelme 按类别打标签。它输出的 JSON 格式也相当友好每个文件对应一张图的标注信息方便后续写脚本转成 VOC、COCO 或自定义数据集格式。1.2 为什么我推荐新手从 Labelme 开始我试过不少标注工具有的界面确实漂亮但安装过程太折腾有的功能很强但输出格式封闭还有的商业软件核心功能要收费。相比之下Labelme 有几个对新手非常友好的点第一完全开源代码和依赖都透明装坏了随时重建环境第二跨平台Windows、macOS、Linux 都能跑第三交互逻辑简洁主流程就是打开文件夹、选标签、画点、保存、下一张没有太多复杂概念第四背靠 Python 生态安装一条命令就能完成后续做格式转换和批量处理也顺手。当然它也有不足比如超大尺寸图像打开时会卡顿、没有云协作功能、多变形只能逐张手工标注。但这些问题通常不影响小规模项目和个人学习使用。对于刚入门的读者先用 Labelme 把图像标注、数据整理、喂给模型这条链路跑通比一开始就折腾企业级标注平台要实际得多。1.3 整体安装与实操路线图这篇文章不会只给你一两条命令就结束。整个流程我拆成四个阶段环境准备、安装验证、界面实操、数据转换。先装 Anaconda 并创建独立环境再通过 pip 安装 Labelme然后启动界面认识各个功能区接着用一组图片走完标注全流程最后讲怎么把 JSON 转换到模型常用的格式并附上常见问题排查表。每一步我都会解释原因比如环境隔离的用意、PyQt5 和 Python 版本的对应关系、标签文件为什么要放在指定位置等。走完这一遍之后你会发现自己不仅会“用”这个工具还对标注数据的结构有了系统认识。后面无论换到其他标注软件还是自己写数据增广脚本都能更快上手。2. 环境准备先把 Python 运行环境安排明白2.1 Python 版本怎么选直接用系统 Python 行不行Labelme 是 Python 应用所以电脑上必须先有 Python 环境。理论上直接去 python.org 下载一个 Python 3.8 或 3.9 安装包也能用但我不建议新手这么干。主要原因有两个一是 Labelme 依赖 PyQt5、numpy、pillow 等一堆第三方库如果直接装在系统 Python 里很容易跟其他项目产生依赖冲突二是以后你大概率还会装 PyTorch、TensorFlow、OpenCV 这些库不同项目对 Python 版本的要求不一样环境乱了会很难收场。我平时推荐安装 Anaconda它自带 Python 解释器、conda 包管理器和很多常用科学计算库。Anaconda 安装包体积比较大初次安装可能需要几分钟但胜在省心。如果磁盘空间有限或者只想要轻量方案可以装 Miniconda只保留 conda 和 Python 基础部分Labelme 的依赖全部交给 pip 解决。我自己在 Windows 上用的就是 Anaconda后续不管是建新环境还是切换 Python 版本都非常方便。2.2 Anaconda 在 Windows 上的安装细节去官网下载 Anaconda 最新版安装包时尽量选择 64 位 Windows 版本。安装过程中有几个选项容易被忽略我这里专门提醒一句在 Advanced Installation Options 页面它会问是否把 Anaconda 添加到 PATH 环境变量建议不要勾选。因为 conda 自带的 Python 版本一旦接管系统命令可能会影响其他软件的 Python 调用。安装完成后我们通过“Anaconda Prompt”这个专用终端进入环境就不需要手动配置 PATH 了。安装好之后先验证一下环境。打开 Anaconda Prompt依次输入python --version和conda --version能看到版本信息就说明基础环境没问题。如果提示找不到命令多半是安装过程被安全软件拦截或者安装路径带了中文字符。卸载重装到纯英文路径一般情况下都能解决。2.3 创建独立的 labelme 工作环境接下来是很多人忽略但非常关键的一步为 Labelme 单独建一个虚拟环境。我习惯在 Anaconda Prompt 里先看一眼当前有哪些环境输入conda env list然后执行conda create -n labelme python3.8 -y这里的labelme是环境名称可以自己改比如label_env、annotate都行。指定python3.8是因为这个版本跟 PyQt5、Labelme 近期版本配合得比较稳。虽然 Python 3.10、3.11 也能装但个别 Windows 机器上会出现 PyQt5 编译组件缺失的问题没必要冒险。创建完成后激活环境conda activate labelme激活后终端前面会出现(labelme)字样表示当前已经进入独立环境。此后所有安装和启动操作都在这个环境里进行。这样做最大的好处是哪怕 Labelme 把依赖库搞乱也不会污染系统里其他项目的 Python 环境反过来其他项目升级 numpy、opencv也不会影响标注工具的运行。3. 正式安装与首次启动从命令行到图形界面3.1 用 pip 安装 Labelme环境激活后接下来就进入正题了。在 Anaconda Prompt 里执行pip install labelme如果只想安装指定版本可以带上版本号比如pip install labelme5.1.1。我遇到过不少朋友反馈说直接安装最新版会有界面小问题我本人用下来 5.x 版本都还算稳定4.x 的 JSON 输出结构跟新版略有差异如果你的项目代码已经适配了旧版就按实际需求固定版本安装。安装过程会拉取 PyQt5、opencv-python、numpy、pillow 等依赖网速正常的话一般几分钟内完成。这里说一个提高成功率的小技巧如果安装时卡在下载大文件可以考虑给 pip 配置国内镜像源比如清华源、阿里源在命令行后面加-i https://pypi.tuna.tsinghua.edu.cn/simple即可。这只是一个网络优化选项不影响任何功能。3.2 验证安装结果安装完成后先验证一下版本号labelme --version能输出版本号说明程序主体已经安装成功。接下来你想直接启动图形界面也行但我建议先做一个小检查确认图形依赖没问题。在命令行输入python -c from PyQt5.QtWidgets import QApplication; print(PyQt5 OK)如果输出PyQt5 OK说明 PyQt5 图形库正常可以放心启动界面。如果这一步报错多半是 PyQt5 没装好重新执行pip install pyqt5就可以。3.3 启动界面与整体布局在 Anaconda Prompt 中激活labelme环境后直接输入labelme界面会弹出来默认是一个主窗口顶部是菜单栏和工具栏左侧是待标注文件列表中间是图像显示区域底部显示当前鼠标位置和图像信息。第一次打开时你会发现“下一步”“保存”等按钮都处于灰色不可用状态因为还没打开任何图片。这时候不要着急先按 3.4 节准备好标签文件再打开图片目录工具栏就会被激活。3.4 准备标签文件 label.txtLabelme 在打开图片前最好先准备好一个标签列表文件它是一份纯文本文件每一行写一个类别名称。比如你要做猫狗分割就建一个label.txt内容为cat dog保存到任意容易找到的位置。然后在 Labelme 菜单栏选择打开目录 Open Dir选中你存放图片的文件夹再把编辑 Edit 菜单里的标签列表指向这个label.txt。这样做的好处有两个一是标注时可以直接从下拉列表选类别不用每次手敲二是避免同一个类在不同图片里出现“猫”“Cat”“mao”这种命名不一致的情况。很多标注事故最后排查发现就是标签名不统一导致模型训练时把同一个类拆成了多个类。3.5 打开图片目录的几种方式Labelme 支持两种打开方式打开单张图片 Open File 和打开整个目录 Open Dir。只修一两张图用 Open File 就行正式标注一个数据集我强烈建议把图片统一放到一个文件夹用 Open Dir 批量管理。点击“打开目录”后左侧文件列表会显示文件夹下所有支持的图片格式常见格式包括.jpg、.png、.bmp右侧主区域显示当前图片下方有上一张、下一张切换按钮。需要注意图片文件夹里最好不要混入其他无关文件比如 Excel 表格、隐藏的 Thumbs.db。Labelme 虽然会按扩展名过滤但文件夹太乱会让你切换图片时心里没底。还有一个细节项目路径最好不要带中文和特殊符号Windows 下出现过因为中文路径导致 JSON 里imagePath记录异常的情况尽量用英文路径最稳妥。4. Labelme 实操全流程从画出第一个多边形到保存 JSON4.1 选择标签类别与创建多边形打开图片目录后界面上工具栏的“创建多边形” Create Polygons 按钮就会亮起来。点击它鼠标会变成十字光标接下来就是标注的核心操作沿着目标物体边缘用鼠标左键逐个打点。每单击一次就生成一个多边形顶点双击鼠标左键多边形闭合弹出标签选择框选中对应类别后回车确认。第一次用多边形标注的人容易犯点打得太密的错误。如果图像里物体轮廓很简单比如一个矩形的包装盒四五个点就够了没必要每隔几个像素打一个点。顶点少后面调整和导出的轮廓数据更干净顶点特别多不仅保存的 JSON 文件变大模型训练时对轮廓起止点捕捉的难度也会增加。当然如果物体形状确实复杂比如叶片边缘、遥感建筑轮廓该加的点还是要加保证贴着真实边缘走。4.2 编辑已有标注调整顶点、移动与撤销标注过程中经常要修改。Labelme 的“编辑多边形” Edit Polygons 功能可以让你调整已经画好的标注。点击左侧工具栏的编辑图标后每个已存在多边形的角点会变成红色小方框你可以按住某个角点拖动来调整位置也可以直接拖动某条边来改变整体位置。对标签类别标错的对象右键菜单里有“删除多边形” Delete Polygon 选项对误操作产生的点可以用 CtrlZ 撤销最近一步。我个人的习惯是先粗标一遍把明显轮廓打出来再切换到编辑模式放大图像细调边缘点。这样比一边打点一边反复改更高效。另外如果多张图里同一个物体的位置和大小都非常接近Labelme 没有直接复制标注到下一张图的功能但你可以通过复制一份 JSON 文件、手动改imagePath字段再在下一张图里用编辑功能把标注拖到新位置这算是老手才会用的小技巧。4.3 三种经常会用到的标注方式矩形、圆形与线条除了多边形Labelme 工具栏里还有创建矩形 Create Rectangle、创建圆 Create Circle、创建线条 Create Line 和创建点 Create Point。矩形框主要用在目标检测场景画的时候从左上角拖到右下角松开鼠标弹窗选类别即可。生成的 JSON 里shape_type是rectangle坐标是左上角和右下角两个点后续写脚本转成 YOLO 格式时只需要计算中心点和宽高。圆形在标注圆形物体、球体、细胞核等场景比较常用只需要确定圆心和半径先单击圆心再单击圆周上一点就完成一个圆。线条和点则适合做关键点检测或者车道线、骨架线这类任务。这里特别提醒一句不同标注类型的shape_type字段不一样如果你的模型只认多边形或矩形那么转换脚本里要分清shape_type再做相应换算否则会出现“画好了但训练代码读取不了”的尴尬。4.4 保存标注结果与 JSON 文件结构详解画完一张图后按 CtrlS 或点击“保存”按钮Labelme 会为该图片生成一个同名但扩展名为.json的文件存放在图片同级目录下。打开这个 JSON你会发现几个核心字段version当前 Labelme 版本信息5.x 版本会对格式做少量兼容处理。imagePath原始图片的相对路径通常就是不带目录的图片文件名。imageData图片的 Base64 编码。如果该字段不为空那么即使图片被单独拿走拿着 JSON 也能还原整张图但这会显著增大文件体积。shapes一个数组包含这张图上所有标注对象每个对象里有label类别名、points坐标点数组、shape_type标注类型、group_id分组 ID等字段。imageWidth和imageHeight原图宽高写转换脚本时可以直接用这两个字段校验坐标是否越界。很多人第一次看到imageData里很长一串 Base64 字符就觉得文件很“脏”其实它是把整张图片编码进了 JSON。Labelme 默认会包含这个字段但如果你的数据集图片已经单独存放建议转换时把imageData置空节省存储空间。4.5 批量切换图片时的高效习惯标注一两张图很轻松但几百张就很考验效率。我总结下来的高效习惯是把图片按类别和场景分好文件夹每个文件夹内放一个label.txt打开目录后按 A 键切换到上一张、D 键切换到下一张标注完一张立刻 CtrlS 保存然后再切下一张。不要等到最后统一保存万一中途软件崩溃或者电脑断电在没有自动保存的情况下所有劳动都可能白费。另外我建议每标完 50 张左右手动检查一下生成的 JSON 文件数量和图片数量是否一致顺手用文本编辑器抽查几个 JSON确认label字段没有空值、points不为空。小批量抽查的成本很低但能提前发现类别名拼写错误、漏标这种问题避免全部标完再返工。5. 数据转换把 JSON 变成模型训练需要的格式5.1 为什么不能直接把 JSON 丢给模型深度学习框架和数据加载器一般不会直接吃 Labelme 的 JSON最常用的数据格式是 VOC 格式XML 标注、COCO 格式JSON 标注以及 YOLO 格式TXT 标注。所以要经过一步“数据转换”。这一步对纯手工标注项目来说几乎是必须的因为你自己定制的数据加载器很可能按 VOC 或 COCO 的规范来写。哪怕模型加载逻辑是自己写的也应该把标注数据统一成固定模板方便后续做数据增强和划分训练集。5.2 JSON 转 COCO 格式的参考脚本我这里放一个结构简单的 Python 转换脚本它会把某个文件夹下的所有 Labelme JSON 汇总成一个 COCO 格式的 JSON。注意这里只处理shape_type为polygon的标注如果你画的是矩形框需要额外处理成bbox。import json import os import glob def labelme_to_coco(img_dir, output_path): images [] annotations [] categories {} ann_id 1 img_id 1 for json_path in glob.glob(os.path.join(img_dir, *.json)): with open(json_path, r, encodingutf-8) as f: data json.load(f) image_name data[imagePath] width data.get(imageWidth, 0) height data.get(imageHeight, 0) images.append({ id: img_id, file_name: image_name, width: width, height: height }) for shape in data[shapes]: label shape[label] if label not in categories: categories[label] len(categories) 1 cat_id categories[label] points shape[points] xs [p[0] for p in points] ys [p[1] for p in points] seg [] for i in range(len(points)): seg.extend([points[i][0], points[i][1]]) x_min min(xs) y_min min(ys) w max(xs) - min(xs) h max(ys) - min(ys) annotations.append({ id: ann_id, image_id: img_id, category_id: cat_id, segmentation: [seg], area: w * h, bbox: [x_min, y_min, w, h], iscrowd: 0 }) ann_id 1 img_id 1 coco_categories [{id: v, name: k} for k, v in categories.items()] coco { images: images, annotations: annotations, categories: coco_categories } with open(output_path, w, encodingutf-8) as f: json.dump(coco, f, ensure_asciiFalse, indent2) if __name__ __main__: labelme_to_coco(./images, ./coco_output.json)这个脚本比较基础核心逻辑是把每张图的shapes铺展开多边形坐标拉成一维数组最小外接矩形的左上角坐标和宽高作为bbox类别从 1 开始自动编号。实际项目里可能需要额外处理group_id、多实例 ID 等逻辑你可以按需扩展。5.3 转成 VOC XML 的思路COCO 格式适合用pycocotools评估的数据集但很多老项目还是用 VOC 格式。VOC 格式本质上是一个 XML 文件里面列出size、object、bndbox、polygon等节点。Labelme 官方仓库里其实提供了一个脚本labelme2voc.py在 GitHub 的examples目录下会把标注转成 PASCAL VOC 目录结构同时生成JPEGImages、Annotations、SegmentationClass、SegmentationObject等文件夹方便直接喂给分割模型。如果不想用官方脚本也可以自己写但本质上就是把 JSON 解析成 XML 字符串。相比 COCO 转换VOC 的 XML 会多一个difficult0/difficult字段表示该目标是否难以识别一般我们都会置为 0。另外提醒一下VOC 格式对文件名有严格要求一般是000001.jpg、000002.jpg这样的六位数字编号如果图片文件名是中文或者带空格要先重命名。5.4 标注数据检查和清洗转换完成后我还会做一轮数据检查。最简单的方法是写个脚本把所有图片的尺寸读出来跟 JSON 里的imageWidth、imageHeight比对如果发现大量不一致多半是图片在标注后被压缩或者替换过需要重新标注。另外也可以把 JSON 里的points坐标画回图像上生成一张带标注的预览图人工扫一眼确认多边形位置基本合理这样能避免“标注了但转出来坐标全飞了”的坑。6. 常见问题排查与避坑指南6.1 安装或启动时遇到依赖报错我在 Windows 上踩过比较多的坑是ModuleNotFoundError: No module named PyQt5。这种情况一般出现在 pip 安装时网络中断或者 PyQt5 没被自动安装上。解决方法是重新执行pip install pyqt5装完再启动。还有一种情况是ImportError: DLL load failed通常是 Python 环境里存在多个 OpenCV 或 numpy 版本冲突可以将环境里的相关包升级到最新版或者干脆删除环境重建。conda remove -n labelme --all conda create -n labelme python3.8 -y pip install labelme这条组合拳能解决 80% 的“玄学报错”。很多时候我不想花时间排查依赖版本之间的复杂问题直接重建干净环境反而最快这也是我前面反复强调环境隔离最主要的原因。6.2 打开界面后工具栏灰色、无法标注如果打开目录后发现“创建多边形”按钮依然是灰色通常有三个原因一是标签列表没设置软件要求先知道有哪些类别你可以在编辑菜单的标签列表里指向label.txt或者直接在标注时手动输入二是当前查看的图片格式不受支持虽然常见格式都能打开但个别 PNG 文件如果用了特殊色彩通道也可能出问题三是窗口太小工具栏按钮被折叠到菜单里了这是 Windows 下高分屏适配不佳导致的把窗口拉大一点或者调整分辨率就能解决。6.3 Python 环境变量和命令行找不到 labelme有朋友反映在 cmd 里输入labelme提示不是内部或外部命令但在 Anaconda Prompt 里就正常。原因是他们没有激活labelme环境当前 cmd 会话用的是系统 Python。Windows 的终端环境是会话级的每次打开新窗口后都要重新执行conda activate labelme不要以为之前激活过就一直有效。如果不想每次都敲这行命令可以在 Anaconda Prompt 里激活后直接输入python -m labelme来启动不过这只是绕过问题治本的办法还是理解 conda 环境生命周期。6.4 标注时鼠标错位、界面卡顿、图像模糊高分屏和缩放比例非 100% 的 Windows 设备上Labelme 可能出现鼠标光标与图像上实际落点位置不一致的问题。这个问题根源是 Qt 在高 DPI 缩放下的坐标映射。如果遇到可以在启动前设置环境变量set QT_AUTO_SCREEN_SCALE_FACTOR0 labelme或者在图像尺寸特别大的情况下先缩小图像再标注。Labelme 加载超大图片时会占用大量内存图像模糊通常是缩放显示导致的不是图像本身损坏不用担心。6.5 高频操作快捷键清单快捷键是提高标注效率的关键。下面是我整理的一份常用快捷键表不少功能藏在右键菜单里直接记快捷键能省不少时间操作快捷键说明上一张/下一张图片A / D翻图时不打断标注状态保存CtrlS建议每张图都立即保存撤销上一步CtrlZ可撤销误加的点放大/缩小Ctrl滚轮精细标注时配合使用删除选中标注CtrlDelete先选中对象再删除完成当前多边形双击鼠标左键闭合多边形并弹出标签选择编辑模式切换CtrlE在创建与编辑之间切换这些快捷键不同版本可能略有差异但大致相同。用熟练之后眼睛只看图像手不离鼠标和 Ctrl 键效率会提升很多。7. 写在最后从标注新手到高效生产的进阶建议现在你已经能把 Labelme 装起来也知道怎么画多边形、怎么保存 JSON、怎么把数据转换成常见格式。最后分享几个我真正在项目里用下来觉得有用的经验。第一不要一上来就标几百张图。建议先用 20 张图跑通完整链路包括标注、格式转换、模型训练和推理确认整条流水线没有问题后再放开手脚批量标注。否则等你辛辛苦苦标完 300 张才发现自己标签类别定义和模型输出不一致返工成本就非常高了。第二类别定义要提前团队对齐最好写一份标注规范文档明确每个类别的边界、遮挡目标怎么标、模糊目标要不要标这在多人协作时尤其重要。第三善用脚本做自动化检查。我每次标注完一批数据都会用几行 Python 检查 JSON 中points是否为空、label是否符合预期列表、是否有多余空白字符这些细枝末节在训练时都会变成大坑。第四如果后续数据量进一步增大可以研究 Labelme 的二次开发接口把简单的标注流程封装成自己的小工具或者引入半自动标注模型做预付标这已经是进阶方向了但对生产效率的提升非常明显。我自己的体会是标注工具本身不复杂真正拉开差距的是对标注规范和数据处理的理解。Labelme 给了我们一个足够开放的起点后面的路完全看你怎么组织数据和优化流程。希望这篇文章能让你少踩几个 Windows 专属的坑把更多时间和精力放到模型本身。如果你在实际操作中遇到其他问题欢迎带着具体的报错信息再来交流大概率是环境或路径上的小问题。