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 ## Labels - custom meta-data in Docker 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 `` / `` 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 ### Naming your labels - namespaces 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; - All (third-party) tools should namespace (prefix) their labels with the reverse DNS notation of a domain controlled by the author of the tool. For example, "com.example.some-label". - Namespaced labels should only consist of lower-cased alphanumeric characters, dots and dashes (in short, `[a-z0-9-.]`), should start *and* end with an alpha numeric character, and may not contain consecutive dots or dashes. - The `com.docker.*`, `io.docker.*` and `com.dockerproject.*` namespaces are reserved for Docker's internal use. - Labels *without* namespace (dots) are reserved for CLI use. This allows end- users to add meta-data to their containers and images, without having to type cumbersome namespaces on the command-line. > **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. ### Storing structured data in 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. ### Adding labels to images; the `LABEL` instruction Adding labels to your LABEL [.][=] ... 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 a `LABEL` 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. ### Querying labels 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" ### Daemon labels 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