Labelme configuration file 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.

The first time you run Labelme it creates a config file at ~/.labelmerc. The config format is one of the three interfaces the project keeps stable, alongside the command line and the JSON annotation format.

How the config file works#

Add only the settings you want to override — the file does not need to be complete. For every available option and its default, read labelme/_config/default_config.yaml in the repository.

To use a config file from somewhere else, or to pass settings inline:

labelme data_annotated --config /path/to/other.yaml
labelme data_annotated --config '{shape_color: {mode: auto, auto: {shift: -2}}}'

Booleans changed in v7. ~/.labelmerc is now parsed with ruamel.yaml as YAML 1.2, so yes, no, on and off in any capitalisation are read as strings rather than booleans. Write true or false. See upgrading to v7.

Saving and session behaviour#

Option	Default	Description
`auto_save`	`true`	Save the annotation without an explicit save action.
`with_image_data`	`false`	Embed the image in the JSON file as base64.
`display_label_popup`	`true`	Ask for a label after drawing a shape.
`keep_prev`	`false`	Carry the previous image's annotations into the next one.
`keep_prev_scale`	`false`	Carry the zoom level across images.
`keep_prev_brightness_contrast`	`false`	Carry brightness and contrast across images.

Labels and validation#

Option	Default	Description
`labels`	empty	The label list offered while annotating.
`flags`	empty	Image-level flags offered as checkboxes.
`label_flags`	empty	Per-label flags, keyed by a regular expression on the label.
`validate_label`	empty	Set to `exact` to reject labels outside `labels`.
`sort_labels`	`true`	List labels alphabetically rather than in the supplied order.
`label_completion`	`startswith`	How the label field completes what you type.
`show_label_text_field`	`true`	Show the free-text label field in the label dialog.
`file_search`	empty	Initial filter applied to the file list.

Appearance#

Option	Default	Description
`language`	empty	Interface language as a locale code such as `ja_JP`. Empty follows the system locale.
`color_theme`	`system`	`system` follows the operating system appearance; `light` or `dark` force one.
`shape_color.mode`	`auto`	`auto`, `uniform` or `by_label`.
`shape_color.auto.shift`	`0`	Shifts the automatic per-label colours so adjacent classes are easier to tell apart.
`shape_color.uniform.color`	`[0, 255, 0]`	The single colour used when `mode` is `uniform`.
`shape_color.by_label.colors`	empty	Explicit per-label colours, with `fallback` for anything unlisted.
`shape.point_size`	`8`	Vertex handle size in pixels.
`shape.show_labels`	`false`	Draw label text on the canvas next to each shape.

The shape section also carries the individual line, fill and vertex colours for drawing, selecting and hovering, each as an RGBA array.

Canvas behaviour#

Option	Default	Description
`epsilon`	`10.0`	Distance in pixels used to find the nearest vertex.
`canvas.fill_drawing`	`true`	Fill a polygon while it is being drawn.
`canvas.double_click`	`close`	What a double-click does. `close` closes the polygon; `None` does nothing.
`canvas.num_backups`	`10`	Maximum undo depth, as edits kept on the backup stack.
`canvas.allow_out_of_bounds_points`	`false`	Allow annotation points beyond the image boundary.
`mask_polygonization.detail`	`80`	Detail level when a mask is converted to a polygon.
`fit_to_content.column`	`true`	Fit the label dialog to its content horizontally.
`fit_to_content.row`	`false`	Fit the label dialog to its content vertically.

AI defaults#

Option	Default	Description
`ai.default`	`Sam2 (balanced)`	The model selected by default for AI-assisted annotation.
`ai.suppress_existing_shape_matches`	`false`	Suppress AI suggestions matching shapes already drawn.

Docks#

The flag_dock, label_dock, shape_dock and file_dock sections each accept show, closable, movable and floatable, all true by default. Set show: false to start with a panel hidden.

Command line reference — the flags that override these per run
Upgrade to v7 — the boolean parsing change
Video frames — keep_prev in use

Updated Aug 26, 2026