LABEL Instruction Reference
Add metadata to an image using key-value pairs
Syntax
The LABEL instruction adds metadata to an image as key-value pairs. Labels are used to organize images, record licensing information, annotate relationships between containers, or provide any other relevant metadata.
The LABEL instruction is used to add metadata to Docker images in the form of key-value pairs. Labels provide a flexible way to organize images, record important information, and help with automation and tooling.
Labels don't affect the behavior of the container but serve as a way to annotate images with information that can be useful for humans and automated systems. You can inspect labels using the docker inspect command.
Description
Labels are key-value pairs that provide metadata about an image. A Dockerfile can include multiple LABEL instructions, but it's generally best practice to combine them into a single instruction to reduce the number of layers.
You can specify multiple labels in a single LABEL instruction:
LABEL version="1.0" description="This is a sample image" maintainer="[email protected]"Label values can include spaces and you can use quotes and backslashes to include special characters:
LABEL description="This is a \"quoted\" string" vendor="Company Name, Inc."For values that contain spaces, you can also use a backslash at the end of each line to break a single instruction over multiple lines:
LABEL description="This is a very long description that \
spans multiple lines in the Dockerfile, \
but represents a single label value."Labels are stored in the image's metadata and don't increase the size of the running container. They can be viewed using docker inspect:
docker inspect --format='{{json .Config.Labels}}' myimage | jqExamples
Basic Usage
Adding simple metadata to an image:
FROM ubuntu:20.04
LABEL version="1.0" \
maintainer="[email protected]" \
description="Base image for our applications"This adds version, maintainer, and description labels to the image.
Standardized Labels
Using standardized label names following OCI (Open Container Initiative) recommendations:
FROM nginx:alpine
LABEL org.opencontainers.image.title="Web Server" \
org.opencontainers.image.description="NGINX with custom configuration" \
org.opencontainers.image.version="1.2.3" \
org.opencontainers.image.created="2025-05-16T10:00:00Z" \
org.opencontainers.image.authors="Company DevOps Team " \
org.opencontainers.image.url="https://github.com/example/repo" \
org.opencontainers.image.source="https://github.com/example/repo" \
org.opencontainers.image.licenses="MIT" This follows the standard label schema defined by OCI, which helps with interoperability between different tools and platforms.
Organization-specific Labels
Adding organization-specific metadata:
FROM python:3.9-slim
LABEL com.example.team="backend" \
com.example.environment="production" \
com.example.app-id="api-12345" \
com.example.release-date="2025-05-16"This uses a namespace (com.example) for organization-specific labels, which helps prevent naming conflicts.
Using Build Arguments
Using ARG instructions to make labels dynamic:
FROM node:18-alpine
ARG VERSION=1.0.0
ARG BUILD_DATE=unknown
ARG VCS_REF=unknown
LABEL org.opencontainers.image.version="${VERSION}" \
org.opencontainers.image.created="${BUILD_DATE}" \
org.opencontainers.image.revision="${VCS_REF}"This allows setting values for labels at build time using --build-arg.
Labels for Documentation
Using labels to document image usage:
FROM postgres:13
LABEL documentation="https://docs.example.com/db-image" \
usage="Docker run --name db -e POSTGRES_PASSWORD=password -p 5432:5432 -d mydb:latest" \
support="[email protected]"This provides helpful information for users of the image, such as documentation links and basic usage instructions.
Multi-stage Build with Labels
Adding labels in a multi-stage build:
FROM node:18 AS builder
WORKDIR /app
COPY . .
RUN npm ci && npm run build
FROM nginx:alpine
# Copy build files from builder stage
COPY --from=builder /app/dist /usr/share/nginx/html
# Add metadata labels
LABEL version="2.0" \
description="Frontend application" \
stage="production"This adds metadata to the final image in a multi-stage build.
Best Practices
- Combine multiple labels: Use a single LABEL instruction with multiple key-value pairs to reduce the number of layers in your image.
- Use namespaces: Prefix your label keys with a namespace (e.g., com.example.project) to avoid conflicts with other labels.
- Follow standard schemas: Consider using standardized label schemas like those defined by the Open Container Initiative (OCI).
- Be consistent: Use a consistent naming convention for your labels across all your images.
- Include useful metadata: Add information that helps identify the image's purpose, version, ownership, and other relevant details.
- Use build args for dynamic values: Combine LABEL with ARG for values that might change between builds, like version numbers or build dates.
- Document your labels: Make sure to document what each label means and how it should be used.
- Don't include sensitive information: Avoid including secrets, passwords, or other sensitive information in labels, as they can be viewed with docker inspect.
Common Label Schemas
Several standardized label schemas have emerged to provide consistent metadata across container images:
The Open Container Initiative (OCI) defines a set of standard annotations for container images:
org.opencontainers.image.created: Date and time when the image was built (ISO 8601 format)org.opencontainers.image.authors: Contact details of the people or organization responsible for the imageorg.opencontainers.image.url: URL to find more information about the imageorg.opencontainers.image.documentation: URL to get documentation about the imageorg.opencontainers.image.source: URL to get the source code for building the imageorg.opencontainers.image.version: Version of the packaged softwareorg.opencontainers.image.revision: Source control revision identifierorg.opencontainers.image.vendor: Name of the distributing entity, organization or individualorg.opencontainers.image.licenses: License(s) under which the contained software is distributedorg.opencontainers.image.title: Human-readable title of the imageorg.opencontainers.image.description: Human-readable description of the image
Many organizations define their own label schemas for internal use, typically using a reverse-DNS notation:
com.example.team: The team responsible for the imagecom.example.environment: The intended deployment environmentcom.example.version: Application versioncom.example.release-date: When the image was released
Working with Labels
Once you've added labels to your images, you can use them in various ways:
You can view the labels of an image using docker inspect:
docker inspect --format='{{json .Config.Labels}}' myimageFor better formatting, you can pipe the output to jq:
docker inspect --format='{{json .Config.Labels}}' myimage | jqYou can filter images based on their labels:
docker images --filter "label=com.example.version=1.0"And similarly for containers:
docker ps --filter "label=com.example.environment=production"You can also set labels for containers in Docker Compose files:
version: '3'
services:
webapp:
image: myapp:latest
labels:
com.example.description: "Web application"
com.example.environment: "staging"Notes and Limitations
- Labels are static metadata that are added to the image at build time and cannot be changed after the image is built.
- Each LABEL instruction creates a new layer in the image, so it's best to combine multiple labels into a single instruction.
- Label keys and values are strings, even if they represent numeric or boolean values.
- There's no built-in validation for label values, so it's up to you to ensure consistency.
- Labels are stored in the image metadata and don't affect the running container.
- Label keys are case-sensitive.
- Labels are visible to anyone who can run
docker inspecton the image, so don't include sensitive information. - If a label key is used multiple times in a Dockerfile, only the last value assigned will be retained.