Labelme annotation JSON format reference

Unofficial preview. Docsbook assembled this page from the public wkentaro/labelme repository. It is not affiliated with, endorsed by, or maintained by the Labelme project. The official documentation lives at labelme.io/docs.

Labelme writes one JSON file per image. This format is one of the three interfaces the project keeps stable, and it is the supported way to consume annotations from your own code.

Top-level fields#

Field	Type	Description
`version`	string	The Labelme annotation format version the file was written with.
`flags`	object	Image-level flags as a map of name to boolean. Empty when no flags were used.
`shapes`	array	The drawn regions. Empty for a classification-only annotation.
`imagePath`	string	Path to the image, resolved relative to the JSON file's own directory. May use Windows separators if the annotation was made on Windows.
`imageData`	string or null	The image itself, base64-encoded, when `--with-image-data` was used. Null or absent otherwise.
`imageHeight`	number	Image height in pixels.
`imageWidth`	number	Image width in pixels.

Shape fields#

Each entry in shapes describes one drawn region:

Field	Type	Description
`label`	string	The name given to this region.
`points`	array	The coordinates defining the shape, as `[x, y]` pairs of floating-point numbers.
`shape_type`	string	Which primitive was drawn: `polygon`, `rectangle`, `circle`, `line` or `point`. A reader should treat a missing or empty value as `polygon`.
`group_id`	number or null	Groups several shapes into one object instance. Null when the shape stands alone.
`flags`	object	Per-shape flags as a map of name to boolean, populated by `--label-flags`.
`mask`	string or null	A base64-encoded mask, when the shape carries one. Null otherwise.

A complete example#

{
  "version": "4.0.0",
  "flags": {},
  "shapes": [
    {
      "label": "shelf",
      "points": [
        [7.942307692307736, 80.76150251617551],
        [171.94230769230774, 714.7615025161755],
        [968.9423076923077, 733.7615025161755]
      ],
      "group_id": null,
      "shape_type": "polygon",
      "flags": {}
    }
  ],
  "imagePath": "apc2016_obj3.jpg",
  "imageData": null,
  "imageHeight": 907,
  "imageWidth": 1210
}

Coordinates are floating point, not integers — they come from where the cursor was, not from a pixel grid.

Notes for anyone writing a reader#

Resolve the image in two steps. Decode imageData when it is present; otherwise join imagePath to the JSON file's directory. examples/utils.py normalises Windows paths before joining.
Default shape_type to polygon. Older files may omit it.
Treat group_id as optional. It is null for most shapes and only meaningful for instance-level tasks.
255 in an exported label PNG means __ignore__, and appears as -1 in the matching npy file. That is the export format rather than this one, but it is where most readers go next.

Read annotations in Python — the reference loader
Core concepts — what these fields mean in practice
Command line reference — the flags that populate them

Updated Aug 26, 2026