moby--moby/docs/sources/userguide/labels-custom-metadata.md

page_title: Labels - custom metadata in Docker
page_description: Learn how to work with custom metadata in Docker, using labels.
page_keywords: Usage, user guide, labels, metadata, docker, documentation, examples, annotating

## Labels - custom metadata in Docker

You can add metadata to your images, containers, and daemons via
labels. Metadata can serve a wide range of uses. Use them to add notes or
licensing information to an image or to identify a host.

A label is a `<key>` / `<value>` pair. Docker stores the values as *strings*.
You can specify multiple labels but each `<key>` / `<value>` must be unique.  If
you specify the same `key` multiple times with different values, each subsequent
value overwrites the previous. Docker applies the last `key=value` you supply.

>**note:** Support for daemon-labels was added in Docker 1.4.1. Labels on
>containers and images are new in Docker 1.6.0

### Naming your labels - namespaces

Docker puts no hard restrictions on the label `key` you. However, labels can
conflict. For example, you can categorize your images by using a chip "architecture"
label:

    LABEL architecture="amd64"

    LABEL architecture="ARMv7"

But a user can label images by building architectural style:

    LABEL architecture="Art Nouveau"

To prevent such conflicts, Docker namespaces label keys using a reverse domain
notation. This notation has the following guidelines:


- All (third-party) tools should prefix their keys with the
  reverse DNS notation of a domain controlled by the author. For
  example, `com.example.some-label`.

- The `com.docker.*`, `io.docker.*` and `com.dockerproject.*` namespaces are
  reserved for Docker's internal use.

- Keys should only consist of lower-cased alphanumeric characters,
  dots and dashes (for example, `[a-z0-9-.]`)

- Keys should start *and* end with an alpha numeric character

- Keys may not contain consecutive dots or dashes.

- Keys *without* namespace (dots) are reserved for CLI use. This allows end-
  users to add metadata to their containers and images, without having to type
  cumbersome namespaces on the command-line.


These are guidelines and are not enforced. Docker does not *enforce* them.
Failing following these guidelines can result in conflicting labels. If you're
building a tool that uses labels, you *should* use namespaces for your label keys.


### Storing structured data in labels

Label values can contain any data type as long as the value can be stored as a
string. For example, consider this JSON:


    {
        "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"]
    }

You can store this struct 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\"]}"

While it is *possible* to store structured data in label values, Docker treats this
data as 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 an image:


    LABEL [<namespace>.]<key>[=<value>] ...

The `LABEL` instruction adds a label to your image, optionally setting its value.
Use surrounding quotes or backslashes for labels that contain
white space character:

    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"

Docker recommends combining labels in a single `LABEL` instruction instead of
using a `LABEL` instruction for each label. Each instruction in a Dockerfile
produces a new layer that can result in an inefficient image if you use many
labels.

You can view the labels via the `docker inspect` command:

    $ 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"}



### Querying labels

Besides storing metadata, you can filter images and labels by label. To 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 of `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"

These labels appear 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