# Labelme: Python image annotation for polygons, rectangles and AI-assisted masks

> Labelme is a Qt desktop tool that writes annotations as JSON. This review covers the v7 platform floor, the privatized import surface, and how to get from install to a first labeled image.

**wkentaro/labelme** — Project brief: Image annotation with Python. Supports polygon, rectangle, circle, line, point, and AI-assisted annotation.

- Repository: https://github.com/wkentaro/labelme
- Website: https://labelme.io
- Stars: 16,200 · Forks: 3,708
- Language: Python
- License: GPL-3.0
- Published: 2026-08-04 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/wkentaro-labelme

## What labelme actually replaces in a labeling workflow

Most labeling problems start with a shape that a bounding box cannot express. A self-stick note photographed at an angle, a crack in a surface, a road boundary: the region is a polygon, not a rectangle. Labelme is a desktop GUI that lets a human draw that polygon, rectangle, circle, line or point on top of an image and saves the result as a JSON file next to the image. The README describes it as a graphical image annotation tool inspired by the MIT LabelMe project, written in Python with Qt for the interface.

The audience is narrow but real. It is for research groups and small teams that already have images and want labeled data without standing up a server, a database or a labeling workforce. The repository ships example directories for bbox detection, classification, instance segmentation, semantic segmentation, primitives and video annotation, which tells you the intended shape of the output: a folder of images plus a folder of JSON files that a training script consumes.

It is not a labeling platform. There is no task queue, no reviewer role, no inter-annotator agreement metric. One person, one machine, one image at a time, with the JSON as the handoff point.

## How the JSON annotation format and the GUI fit together

The architecture is deliberately thin. A Qt application opens an image, you draw shapes, and on save it writes a JSON file. The README states that annotations are saved as a JSON file, and that the on-disk JSON annotation format is one of the three interfaces the project keeps stable, alongside the command-line interface and the ~/.labelmerc config format. Everything else, including the Python import surface, is described as internal and subject to renaming without notice.

That is the most consequential design decision in v7. The internal modules were privatized and renamed with underscore prefixes, so imports such as labelme.app, labelme.utils and labelme.widgets no longer work. The README points to examples/utils.py as copy-and-adapt reference code that reads the JSON annotation format without depending on labelme. If your pipeline currently does `import labelme.utils` to load shapes, that pipeline breaks on upgrade, and the recommended fix is not a shim but vendoring the reader.

Config lives in ~/.labelmerc and is parsed with ruamel.yaml under YAML 1.2. The practical effect: the boolean spellings yes, no, on and off in any capitalization are now read as strings rather than booleans. Anyone who wrote `auto_save: yes` has a config that silently stopped behaving as a boolean.

AI assistance is part of the same flow rather than a separate service. The feature list names point-to-polygon and point-to-mask annotation through SAM and EfficientSAM models, and text-to-annotation through YOLO-world and SAM3. The dependency list in pyproject.toml includes onnxruntime and osam, which is consistent with running those models locally rather than calling a hosted API. The README does not document model download sizes, first-run latency or where weights are cached, so treat the AI path as something to measure on your own hardware before promising it to a team.

## Installing labelme with pip and labeling a first image

The README gives three installation routes: pip, a paid standalone executable from labelme.io, and native Linux distribution packages. The pip route is the one you can script.

The package requires Python 3.12 or newer on the v7 line, and the install pulls PySide6 rather than PyQt5.

```bash
pip install labelme
```

To track the repository instead of the released wheel, the README shows a git install.

```bash
pip install git+https://github.com/wkentaro/labelme.git
```

If you need to stay on PyQt5, Qt5 or Python 3.10 and 3.11, the README says to pin the maintenance line.

```bash
pip install 'labelme<7'
```

Running labelme with no arguments opens the GUI. The tutorial example in the repository works on a single image, and the --output flag sends the JSON somewhere other than next to the image.

```bash
cd examples/tutorial
labelme apc2016_obj3.jpg --output annotations/
```

You should end up with a JSON file in the annotations directory describing the shapes you drew. Two more flags appear in the README: --with-image-data embeds the image data in the JSON, and --labels takes a comma-separated list to constrain the label set, shown as highland_6539_self_stick_notes,mead_index. Constraining labels up front is worth doing on any project with more than one annotator, because free-text labels drift.

The interface is translated into 20 languages, and the README shows the environment variable form for forcing one.

```bash
LANG=ja_JP.UTF-8 labelme
```

## Where labelme stops being the right tool

The v7 platform floor is the first hard boundary. Python 3.12 to 3.14, Qt6 through PySide6, and a 64-bit macOS, Windows or Linux. Older operating systems that only Qt5 supported are no longer covered. If your lab machines are pinned to an older OS or to Python 3.10, you are on v6.3.x, and the README is explicit about what that means: critical fixes only, on a best-effort basis, with no release cadence or SLA, limited to security vulnerabilities, data-loss or annotation-corruption bugs, and install or launch breakage from upstream dependency drift. Feature backports are out of scope. That is a maintenance line, not a supported branch, and planning new annotation work on it is a mistake.

The second boundary is the missing library API. If your training code imports labelme internals, v7 is a breaking change with no compatibility layer. The project's position is that labelme is an application, and the stable contracts are the CLI, the JSON format and the config file. Teams that treated it as a library have to rewrite that part.

The third is scale. Nothing in the README describes multi-user coordination, review queues or labeling throughput. Labelme is a single-user desktop editor. If you need hundreds of annotators, an audit trail and per-task assignment, a server-based labeling platform is the correct category, and labelme is not competing there.

Finally, the AI-assisted modes depend on local model inference. The README lists the model families but does not state memory requirements or GPU expectations. On a laptop without a capable GPU, point-to-polygon assistance may be slower than drawing the polygon by hand, and you will not know until you try it on your own images.

## Labelme compared with CVAT and other server-based annotators

The closest alternative category is a browser-based annotation server such as CVAT, which runs as a web application with accounts, tasks and a review workflow. The difference is architectural, not cosmetic. Labelme writes a JSON file to your local disk and has no server process; CVAT keeps annotations in a database behind an API, which is what makes multi-user assignment and progress tracking possible. If your bottleneck is coordination across many annotators, labelme's file-per-image model becomes the problem, because merging and versioning thousands of loose JSON files is your job.

For pure bounding-box work, tools built around rectangle-only labeling are faster to operate than a general editor, because they remove the shape palette and the polygon vertex editing. Labelme's breadth, five shape primitives plus flags for classification, is exactly what makes it slower for a single-shape task.

There is also the labelme.io standalone app. The README frames it as the option for people who do not want to manage Python or Qt dependencies, and notes it is a one-time payment for lifetime access that helps maintain the project. That is a licensing and convenience decision rather than a technical one, and it is worth knowing that the same annotation format is the output either way.

## Maintenance, upgrades and the GPL-3.0-only license

The repository is not archived, and the last push was on 2026-08-27, the same date as the v7.2.0 release. Releases are frequent: v7.1.0rc1 on 2026-08-18, v7.1.0 on 2026-08-21, v7.2.0 on 2026-08-27. That cadence is a real signal, but it also means the upgrade path is not frozen. The v6 to v7 jump bundled four separate breaking changes: the Qt binding swap to PySide6, the Python minimum moving to 3.12, the loss of the import surface, and the YAML 1.2 config parsing change. A team that skipped the release notes and ran a routine upgrade would hit all four at once.

The project follows SPEC 0 for dropping Python versions, in step with numpy, scipy and scikit-image. That policy is predictable, but it ties labelme's supported Python range to its scientific dependencies, so a Python upgrade you postpone elsewhere will eventually force a labelme upgrade here.

On licensing: pyproject.toml declares GPL-3.0-only, and the classifiers list GNU General Public License v3. Labelme is distributed as an application, and the README states plainly that it exposes no stable Python API. For internal labeling that distinction rarely matters. If you intend to embed labelme in a product you distribute, GPL-3.0-only is a copyleft license and the obligations are substantial. That is a question for your own legal review, not something this article can settle.

One upgrade cost is easy to overlook: the repository has a check_translate target described as a CI and release gate that fails if translation catalogs are stale. That is the project's problem, not yours, but it explains why translation updates ship alongside feature releases.

## Conclusion

Adopt labelme if your team labels images in-house, wants a GUI that runs on a normal desktop, and can read the JSON output with your own script. Do not adopt it if you need a stable Python import surface, since v7 privatized the internal modules, or if you are stuck on Python 3.10 or 3.11 and Qt5, where the v6.3.x line only takes critical fixes with no release cadence. Before committing, verify three things: that your target machines run a 64-bit macOS, Windows or Linux with Python 3.12 to 3.14, that your existing ~/.labelmerc booleans use true and false rather than yes, no, on or off, and that your downstream parser reads the JSON format directly instead of importing labelme. The GPL-3.0-only license is the last gate, and it matters most if you plan to ship labelme inside a closed product.

## FAQ

### Is Labelme free to use?

The source is GPL-3.0-only and installable from PyPI with pip, so the tool itself is free. The README separately offers a paid standalone executable from labelme.io as a one-time payment for lifetime access, described as a way to install without Python or Qt dependencies.

### Is labelme open source?

Yes. The repository is public, the primary language is Python, and pyproject.toml declares the license as GPL-3.0-only with the GNU General Public License v3 classifier.

### How to install labelme?

The README lists three options: pip install labelme, a standalone executable from labelme.io, or a native package from your Linux distribution. The pip route requires Python 3.12 or newer on the v7 line and pulls PySide6.

### How to use labelme in Python?

Labelme is an application rather than a library, and v7 privatized its internal modules, so imports like labelme.utils no longer work. The README directs you to examples/utils.py as copy-and-adapt reference code that reads the JSON annotation format without depending on labelme.

### How to use labelme for yolo?

The README does not document a YOLO export path. It lists VOC-format exports for semantic and instance segmentation, COCO-format exports for instance segmentation, and YOLO-world as one of the models behind AI text-to-annotation, which is a different thing from converting labels to YOLO training format.

### How to install labelme on mac?

The pip install applies on macOS, and v7 requires a 64-bit macOS because Qt6 is the only supported Qt binding. The README does not give a separate macOS-specific procedure beyond the three installation options.

## Sources

- [Official documentation](https://labelme.io)
- [Official README](https://github.com/wkentaro/labelme#readme)
- [Project repository](https://github.com/wkentaro/labelme)
- [Release notes](https://github.com/wkentaro/labelme/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/wkentaro-labelme