---
title: Annotations
description: Annotations specify additional metadata about OCI images
keywords: build, buildkit, annotations, metadata
---

Annotations provide descriptive metadata for images. Use annotations to record
arbitrary information and attach it to your image, which helps consumers and
tools understand the origin, contents, and how to use the image.

Annotations are similar to, and in some sense overlap with, [labels]. Both
serve the same purpose: attach metadata to a resource. As a general principle,
you can think of the difference between annotations and labels as follows:

- Annotations describe OCI image components, such as [manifests], [indexes],
  and [descriptors].
- Labels describe Docker resources, such as images, containers, networks, and
  volumes.

The OCI image [specification] defines the format of annotations, as well as a set
of pre-defined annotation keys. Adhering to the specified standards ensures
that metadata about images can be surfaced automatically and consistently, by
tools like Docker Scout.

Annotations are not to be confused with [attestations]:

- Attestations contain information about how an image was built and what it contains.
  An attestation is attached as a separate manifest on the image index.
  Attestations are not standardized by the Open Container Initiative.
- Annotations contain arbitrary metadata about an image.
  Annotations attach to the image [config] as labels,
  or on the image index or manifest as properties.

## Add annotations

You can add annotations to an image at build-time, or when creating the image
manifest or index.

> **Note**
> 
> The Docker Engine image store doesn't support loading images with
> annotations. To build with annotations, make sure to push the image directly
> to a registry, using the `--push` CLI flag or the
> [registry exporter](../exporters/image-registry.md).

To specify annotations on the command line, use the `--annotation` flag for the
`docker build` command:

```console
$ docker build --push --annotation "foo=bar" .
```

If you're using [Bake](../bake/_index.md), you can use the `annotations`
attribute to specify annotations for a given target:

```hcl
target "default" {
  output = ["type=registry"]
  annotations = ["foo=bar"]
}
```

For examples on how to add annotations to images built with GitHub Actions, see
[Add image annotations with GitHub Actions](../ci/github-actions/annotations.md)

You can also add annotations to an image created using `docker buildx
imagetools create`. This command only supports adding annotations to an index
or manifest descriptors, see
[CLI reference](../../engine/reference/commandline/buildx_imagetools_create.md#annotations).

## Inspect annotations

To view annotations on an **image index**, use the `docker buildx imagetools
inspect` command. This shows you any annotations for the index and descriptors
(references to manifests) that the index contains. The following example shows
an `org.opencontainers.image.documentation` annotation on a descriptor, and an
`org.opencontainers.image.authors` annotation on the index.

```console {hl_lines=["10-12","19-21"]}
$ docker buildx imagetools inspect <IMAGE> --raw
{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.index.v1+json",
  "manifests": [
    {
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "digest": "sha256:d20246ef744b1d05a1dd69d0b3fa907db007c07f79fe3e68c17223439be9fefb",
      "size": 911,
      "annotations": {
        "org.opencontainers.image.documentation": "https://foo.example/docs",
      },
      "platform": {
        "architecture": "amd64",
        "os": "linux"
      }
    },
  ],
  "annotations": {
    "org.opencontainers.image.authors": "dvdksn"
  }
}
```

To inspect annotations on a manifest, use the `docker buildx imagetools
inspect` command and specify `<IMAGE>@<DIGEST>`, where `<DIGEST>` is the digest
of the manifest:

```console {hl_lines="22-25"}
$ docker buildx imagetools inspect <IMAGE>@sha256:d20246ef744b1d05a1dd69d0b3fa907db007c07f79fe3e68c17223439be9fefb --raw
{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.manifest.v1+json",
  "config": {
    "mediaType": "application/vnd.oci.image.config.v1+json",
    "digest": "sha256:4368b6959a78b412efa083c5506c4887e251f1484ccc9f0af5c406d8f76ece1d",
    "size": 850
  },
  "layers": [
    {
      "mediaType": "application/vnd.oci.image.layer.v1.tar+gzip",
      "digest": "sha256:2c03dbb20264f09924f9eab176da44e5421e74a78b09531d3c63448a7baa7c59",
      "size": 3333033
    },
    {
      "mediaType": "application/vnd.oci.image.layer.v1.tar+gzip",
      "digest": "sha256:4923ad480d60a548e9b334ca492fa547a3ce8879676685b6718b085de5aaf142",
      "size": 61887305
    }
  ],
  "annotations": {
    "index,manifest:org.opencontainers.image.vendor": "foocorp",
    "org.opencontainers.image.source": "https://git.example/foo.git",
  }
}
```

## Specify annotation level

By default, annotations are added to the image manifest. You can specify which
level(s) to attach the manifest to, by prefixing the annotation string with a
special type declaration:

- `manifest`: annotates manifests.
- `index`: annotates the root index.
- `manifest-descriptor`: annotates manifest descriptors in the index.
- `index-descriptor`:  annotates the index descriptor in the image layout.

For example, to build an image with the annotation `foo=bar` attached to the
image index:

```console
$ docker build --tag <IMAGE> --push --annotation "index:foo=bar" .
```

It's possible to specify types, separated by a comma, to add the annotation to
more than one level. The following example creates an image with the annotation
`foo=bar` on both the image index and the image manifest:

```console
$ docker build --tag <IMAGE> --push --annotation "index,manifest:foo=bar" .
```

You can also specify a platform qualifier in the type prefix, to annotate only
components matching specific OS and architectures. The following example adds
the `foo=bar` annotation only to the `linux/amd64` manifest:

```console
$ docker build --tag <IMAGE> --push --annotation "manifest[linux/amd64]:foo=bar" .
```

## Related information

Related articles:

- [Add image annotations with GitHub Actions](../ci/github-actions/annotations.md)
- [Annotations OCI specification][specification]

Reference information:

- [`docker buildx build --annotation`](../../engine/reference/commandline/buildx_build.md#annotation)
- [Bake file reference: `annotations`](../bake/reference.md#targetannotations)
- [`docker buildx imagetools create --annotation`](../../engine/reference/commandline/buildx_imagetools_create.md#annotation)

<!-- links -->

[specification]: https://github.com/opencontainers/image-spec/blob/main/annotations.md
[attestations]: ../attestations/_index.md
[config]: https://github.com/opencontainers/image-spec/blob/main/config.md
[descriptors]: https://github.com/opencontainers/image-spec/blob/main/descriptor.md
[indexes]: https://github.com/opencontainers/image-spec/blob/main/image-index.md
[labels]: ../../config/labels-custom-metadata.md
[manifests]: https://github.com/opencontainers/image-spec/blob/main/manifest.md