Docker labels let you attach arbitrary metadata to your containers, images, volumes, and other resources. You can tag your Docker objects with information specific to your organization, workflow, or toolchain.

Labels are meant to be an open-ended classification system that you can adapt to your own needs. Here's how to create new labels and use them to filter objects returned by the Docker CLI.

Supported Object Types

You can use labels with the following Docker objects:

• Containers
• Images
• Volumes
• Networks
• Daemon instances
• Swarm nodes and services

Each object type supports labels as part of its CLI command group. It doesn't matter whether you're using

        docker image
    

,

        docker network
    

, or

        docker volume
    

.

Adding Labels

Labels are added at the time you create an object. They cannot be modified after the initial creation; you need to delete the object and replace it with a new version if changes are necessary. An exception is labels assigned to Docker Swarm nodes and services which can be updated dynamically at any time.

The

        --label
    

flag is used to set labels. Each label is a key-value pair with the key and value separated by an equals (

        =
    

) sign:

docker run my-image:latest --label demo-label=example-value

Label keys can contain lowercase alphanumeric characters, periods (.) and hyphens (-). They must start and end with an alphanumeric character. DNS notation rules are followed so multiple consecutive periods and hyphens are disallowed.

Docker accepts any string as label values, although be mindful that no serialization or casting occurs. Complex values such as JSON or XML will be stored and retrieved as a plain string.

Best Practices for Labels

Docker suggests some guidelines for naming your labels that enhance interoperability across the ecosystem. It advises use of namespaced labels using the reverse DNS notation favored by app stores and package managers:

docker run my-image:latest --label=com.example.demo-label=example-value

This practice helps avoid key naming conflicts when labels are set by tools in your build system. Many automation facilities add their own labels to the Docker objects they create to facilitate tracking and management. Docker doesn't support duplicate label keys and using the same key twice causes the last repetition's value to be used.

Docker reserves some namespaces for internal use by the CLI. You should not prefix your keys with any of the following namespaces:

• com.docker.*
• io.docker.*
• org.dockerproject.*

Prefix all your labels with your own domain name unless there's a compelling reason not to. Docker's CLI doesn't enforce any of the guidelines but following them helps minimize the risk of a common key like name or version being unintentionally overwritten.

Inspecting Labels

The docker inspect command includes a list of assigned labels as part of its output. This works with containers and images identified by ID or name. Labels used with networks and volumes are accessed via the inspect sub-command of those CLI groups, such as docker network inspect my-network.

docker inspect output can be hard to digest as-is. The labels section will be buried within the JSON emitted to your terminal. You can use the --format flag to view the labels in isolation. Selecting JSON as the output format and piping the resulting string through jq gives you a colorized list of labels for easy reading.

docker inspect my-container --format='{{json .Config.Labels}}' | jq

Filtering Object Lists

Docker CLI commands like docker ps and docker images that produce a list of objects can be filtered to only show items with a given set of labels.

Here's how to show containers with the demo label set to example:

docker ps --filter "label=com.example.demo=example"

If you want to filter to multiple labels, repeat the --filter flag:

docker ps --filter "label=a=1" --filter "label=b=2"

Sometimes you might want to show all objects with a given label. Specify the label's key name but omit the value to achieve this:

docker ps --filter "label=com.example.demo"

Any container with the com.example.demo label would be included in the command's output, irrespective of the value the label's been assigned.

Label Specifications

The OCI Containers Specification defines several conventional labels that encapsulate common use cases for container images. These exist within the org.opencontainers.image namespace.

• org.opencontainers.image.created - Image creation time.
• org.opencontainers.image.url - URL to get information about the image.
• org.opencontainers.image.version - Version of the main software inside the container (not the image's version).
• org.opencontainers.image.licenses - Container licensing information.
• org.opencontainers.image.title - A human-readable name for the container.

You can view the full list of OCI labels in the specification. It's a good idea to use the OCI labels if you find yourself adding any of this information to your images. They help make your image compatible with community tools that surface and filter this metadata.

Adding Labels at Image Build Time

You can set labels at image build time using the LABEL instruction in your Dockerfile. The labels will be applied to the image, not to the containers started from it. Images also inherit any labels defined by their parents. A layer that sets a label that's already been created by an earlier one will override the original value.

LABEL com.example.demo=example com.example.example=demo
    
    
            LABEL com.example.image=service

You can combine multiple labels into a single LABEL instruction or repeat the instruction several times. The impact is the same regardless as all labels will ultimately be included in your image.

Summary

Labels are a mechanism to add your own metadata to your Docker objects. While labels are intentionally arbitrary and open-ended, you should try to follow the OCI specifications when setting commonly used fields.

Setting labels lets you attach any extra information which might be relevant to an object. Defining a set of reference labels in your organization would let anyone run docker inspect to get critical container details, instead of cross-referencing external documentation. Labels also let you filter Docker CLI output, providing a more streamlined management experience.