4.2.14.1 LABEL Image Labels

LABEL image labels are the complete set of key-value metadata attached to a given image through one or more LABEL instructions, collectively forming a queryable, structured description of the image that exists independently of, and persists alongside, its actual filesystem layers.

Labels Accumulate Across Instructions and Stages

Multiple LABEL instructions throughout a Dockerfile all contribute to the same final set of labels on the resulting image, with a later instruction's value taking precedence if the same key is set more than once.

LABEL maintainer="team@example.com"
LABEL version="1.0"
LABEL version="2.0"

The final image's version label reflects "2.0", since the later instruction overrides the earlier one for the same key.

Labels Inherited From Base Images

A base image's own labels carry forward into images built on top of it, unless explicitly overridden — meaning a final image's complete label set can include labels the author of the Dockerfile never directly set themselves.

docker inspect python:3.12-slim --format '{{json .Config.Labels}}'
docker build -t myapp .
docker inspect myapp --format '{{json .Config.Labels}}'

Comparing these two outputs often reveals labels present in the base image that simply carried forward into the derived image.

Querying Across Many Images by Label

A consistent labeling scheme across an organization's images makes it practical to query and act on them collectively, based on shared attributes recorded as labels.

docker images --filter "label=team=platform"

Using Labels for Automated Cleanup or Auditing

Labels recording build metadata — a build date, a source commit — support automated processes that need to identify and act on images meeting specific criteria, such as cleaning up images older than a certain age.

LABEL build.date="2026-06-24"
LABEL build.commit="a1b2c3d"

Why a Complete, Considered Label Set Matters

Treating an image's label set as a deliberate, structured piece of metadata — rather than an afterthought — makes images significantly more useful to query, audit, and manage at scale across an organization with many images to track.