Understanding Docker Object Labels

--- description: Learn about labels, a tool to manage metadata on Docker objects. keywords: labels, metadata, docker, annotations title: Docker object labels aliases: - /engine/userguide/labels-custom-metadata/ - /config/labels-custom-metadata/ --- Labels are a mechanism for applying metadata to Docker objects, including: - Images - Containers - Local daemons - Volumes - Networks - Swarm nodes - Swarm services You can use labels to organize your images, record licensing information, annotate relationships between containers, volumes, and networks, or in any way that makes sense for your business or application. ## Label keys and values A label is a key-value pair, stored as a string. You can specify multiple labels for an object, but each key must be unique within an object. If the same key is given multiple values, the most-recently-written value overwrites all previous values. ### Key format recommendations A label key is the left-hand side of the key-value pair. Keys are alphanumeric strings which may contain periods (`.`), underscores (`_`), slashes (`/`), and hyphens (`-`). Most Docker users use images created by other organizations, and the following guidelines help to prevent inadvertent duplication of labels across objects, especially if you plan to use labels as a mechanism for automation. - Authors of third-party tools should prefix each label key with the reverse DNS notation of a domain they own, such as `com.example.some-label`. - Don't use a domain in your label key without the domain owner's permission. - The `com.docker.*`, `io.docker.*`, and `org.dockerproject.*` namespaces are reserved by Docker for internal use. - Label keys should begin and end with a lower-case letter and should only contain lower-case alphanumeric characters, the period character (`.`), and the hyphen character (`-`). Consecutive periods or hyphens aren't allowed. - The period character (`.`) separates namespace "fields". Label keys without namespaces are reserved for CLI use, allowing users of the CLI to interactively label Docker objects using shorter typing-friendly strings. These guidelines aren't currently enforced and additional guidelines may apply to specific use cases. ### Value guidelines Label values can contain any data type that can be represented as a string, including (but not limited to) JSON, XML, CSV, or YAML. The only requirement is that the value be serialized to a string first, using a mechanism specific to the type of structure. For instance, to serialize JSON into a string, you might

This document explains Docker labels, a key-value metadata system for Docker objects like images, containers, volumes, and networks. It outlines the purpose of labels for organization and annotation, and provides guidelines for key formatting to avoid conflicts, recommending reverse DNS notation for third-party tools. Label values can be any string-serialized data, including JSON, XML, CSV, or YAML.