page_title: Labels - custom meta-data in Docker page_description: Learn how to work with custom meta-data in Docker, using labels. page_keywords: Usage, user guide, labels, meta-data, docker, documentation, examples, annotating
Docker enables you to add meta-data to your images, containers, and daemons via labels. Meta-data can serve a wide range of uses ranging from adding notes or licensing information to an image to identifying a host.
Labels in Docker are implemented as <key>
/ <value>
pairs and values are
stored as strings.
note: Support for daemon-labels was added in docker 1.4.1, labels on containers and images in docker 1.6.0
Docker puts no hard restrictions on the names you pick for your labels, however, it's easy for labels to "conflict".
For example, you're building a tool that categorizes your images in architectures, doing so by using an "architecture" label;
LABEL architecture="amd64"
LABEL architecture="ARMv7"
But a user decided to label images by Architectural style
LABEL architecture="Art Nouveau"
To prevent such conflicts, Docker uses the convention to namespace label-names, using a reverse domain notation;
[a-z0-9-.]
), should start and end with an alpha
numeric character, and may not contain consecutive dots or dashes.com.docker.*
, io.docker.*
and com.dockerproject.*
namespaces are
reserved for Docker's internal use.Note: Even though Docker does not enforce you to use namespaces, preventing to do so will likely result in conflicting usage of labels. If you're building a tool that uses labels, you should use namespaces for your labels.
Labels can store any type of data, as long as its stored as a string.
{
"Description": "A containerized foobar",
"Usage": "docker run --rm example/foobar [args]",
"License": "GPL",
"Version": "0.0.1-beta",
"aBoolean": true,
"aNumber" : 0.01234,
"aNestedArray": ["a", "b", "c"]
}
Which can be stored in a label by serializing it to a string first;
LABEL com.example.image-specs="{\"Description\":\"A containerized foobar\",\"Usage\":\"docker run --rm example\\/foobar [args]\",\"License\":\"GPL\",\"Version\":\"0.0.1-beta\",\"aBoolean\":true,\"aNumber\":0.01234,\"aNestedArray\":[\"a\",\"b\",\"c\"]}"
Note: Although the example above shows it's possible to store structured data in labels, Docker does not treat this data any other way than a 'regular' string. This means that Docker doesn't offer ways to query (filter) based on nested properties. If your tool needs to filter on nested properties, the tool itself should implement this.
LABEL
instructionAdding labels to your
LABEL [<namespace>.]<name>[=<value>] ...
The LABEL
instruction adds a label to your image, optionally setting its value.
Quotes surrounding name and value are optional, but required if they contain
white space characters. Alternatively, backslashes can be used.
Label values only support strings
LABEL vendor=ACME\ Incorporated
LABEL com.example.version.is-beta
LABEL com.example.version="0.0.1-beta"
LABEL com.example.release-date="2015-02-12"
The LABEL
instruction supports setting multiple labels in a single instruction
using this notation;
LABEL com.example.version="0.0.1-beta" com.example.release-date="2015-02-12"
Wrapping is allowed by using a backslash (\
) as continuation marker;
LABEL vendor=ACME\ Incorporated \
com.example.is-beta \
com.example.version="0.0.1-beta" \
com.example.release-date="2015-02-12"
You can view the labels via docker inspect
$ docker inspect 4fa6e0f0c678
...
"Labels": {
"vendor": "ACME Incorporated",
"com.example.is-beta": "",
"com.example.version": "0.0.1-beta",
"com.example.release-date": "2015-02-12"
}
...
$ docker inspect -f "{{json .Labels }}" 4fa6e0f0c678
{"Vendor":"ACME Incorporated","com.example.is-beta":"","com.example.version":"0.0.1-beta","com.example.release-date":"2015-02-12"}
note: We recommend combining labels in a single
LABEl
instruction in stead of using aLABEL
instruction for each label. Each instruction in a Dockerfile produces a new layer, which can result in an inefficient image if many labels are used.
Besides storing meta-data, labels can be used to filter your images and containers.
List all running containers that have a com.example.is-beta
label;
# List all running containers that have a `com.example.is-beta` label
$ docker ps --filter "label=com.example.is-beta"
List all running containers with a "color" label set to "blue";
$ docker ps --filter "label=color=blue"
List all images with "vendor" "ACME"
$ docker images --filter "label=vendor=ACME"
docker -d \
--dns 8.8.8.8 \
--dns 8.8.4.4 \
-H unix:///var/run/docker.sock \
--label com.example.environment="production" \
--label com.example.storage="ssd"
And can be seen as part of the docker info
output for the daemon;
docker -D info
Containers: 12
Images: 672
Storage Driver: aufs
Root Dir: /var/lib/docker/aufs
Backing Filesystem: extfs
Dirs: 697
Execution Driver: native-0.2
Kernel Version: 3.13.0-32-generic
Operating System: Ubuntu 14.04.1 LTS
CPUs: 1
Total Memory: 994.1 MiB
Name: docker.example.com
ID: RC3P:JTCT:32YS:XYSB:YUBG:VFED:AAJZ:W3YW:76XO:D7NN:TEVU:UCRW
Debug mode (server): false
Debug mode (client): true
Fds: 11
Goroutines: 14
EventsListeners: 0
Init Path: /usr/bin/docker
Docker Root Dir: /var/lib/docker
WARNING: No swap limit support
Labels:
com.example.environment=production
com.example.storage=ssd