4.2.14 LABEL

LABEL is the Dockerfile instruction used to attach arbitrary metadata to an image as key-value pairs, useful for recording information like the maintainer, version, source repository, or any other descriptive detail that tooling or people might want to query later.

Basic Usage

LABEL accepts one or more key-value pairs, attaching them directly to the image's metadata.

LABEL maintainer="team@example.com"
LABEL version="2.3.0"

Multiple labels can also be set in a single instruction.

LABEL maintainer="team@example.com" \
      version="2.3.0" \
      description="Backend API service"

Inspecting Labels on an Image

Labels attached to an image can be retrieved directly without needing to consult the original Dockerfile.

docker inspect myapp:1.0 --format '{{json .Config.Labels}}'

This is useful for anyone who only has access to the built image, allowing them to discover metadata the image's author chose to record.

Filtering Containers or Images by Label

Labels can be used to filter and select containers or images matching specific criteria, which is useful for automation and tooling that needs to operate on a specific subset of resources.

docker ps --filter "label=environment=production"
docker images --filter "label=maintainer=team@example.com"

Following Established Label Conventions

Several established conventions exist for common label keys (such as those defined by the OCI image specification), and following them improves interoperability with tooling that expects labels in a particular format.

LABEL org.opencontainers.image.source="https://github.com/example/myapp"
LABEL org.opencontainers.image.version="2.3.0"

Why LABEL Matters

LABEL provides a flexible, standardized way to attach descriptive metadata directly to an image, supporting both human understanding (knowing who maintains an image, what it is for) and automated tooling that needs to query, filter, or act on images and containers based on their attached metadata.