Annotation JSON files store image paths, not pixels

A LabelMe v5 annotation file for a 4 MB photograph weighed about 5.5 MB on disk. The shapes themselves were a few kilobytes. The rest was the image, base64-encoded inside the JSON.

That decision made the file self-contained, which had real value in a 2016 codebase: copy one .json and you had both the annotation and the image. By 2026 it mostly meant your annotation repo was unusable in git, code review on labels was impossible, and a directory of a thousand annotations on a 30 GB photo set turned into 60 GB of duplicated pixels.

LabelMe v6 stores a file path reference instead.

What changed

imageData is null by default. The annotation JSON keeps the shape list, the label names, and an imagePath that points at the original image alongside the JSON. The image bytes are no longer duplicated into the annotation.

v5 files still open. If an old file has imageData populated, LabelMe still reads it. Nothing on disk has to be migrated.

You can opt back in. Enable File → Save With Image Data in the menu, or set with_image_data: true in your config file. Useful when you need a single file to travel without the images alongside (sharing a snippet, attaching to a bug report).

What you get back

• Diffs you can read. Changing one polygon used to look like rewriting a 5 MB binary blob. Now it's a few lines of JSON.
• Repos that fit in git. A thousand annotations is a few megabytes instead of tens of gigabytes. LFS becomes optional, not mandatory.
• Fast saves. With auto-save on by default, every shape edit writes the file. A few kilobytes write instantly; 5 MB writes noticeably.
• Cleaner code review on labels. When labels live in the same repo as your model code, PR diffs actually show what changed.

When to keep the old behavior

• You're emailing a single annotation file and want the recipient to be able to open it without the source image.
• You're attaching an annotation to a bug report and the image isn't reproducible from a path.
• Your pipeline genuinely benefits from a self-contained file. Some downstream tooling assumes the image is inline.

For those cases, Save With Image Data is still there. For everyone else, the new default is the better one.

Where to find it

Update to LabelMe v6 or later from the download page. The new default applies to all new saves. Existing files keep whatever format they were saved in.

See the v6.0 release notes on GitHub for the full changelog. The default flip and the store_data → with_image_data rename landed in #1814.

If a downstream script breaks on the new format, open an issue or ask on Discord.