What Is a Docker Image Manifest?
Docker manifests describe the layers inside an image. A manifest enables exact comparison of two images, even if they have different tags assigned. Manifests are expressed in JSON and contain information about the images layers and architectures. The Docker client uses manifests to work out whether an image is compatible with the current device. It then uses the information to determine how to start new containers. The Manifest Format  The manifest schema is currently at version 2. A complete file will declare its schema version and then a list of manifest entries available for the image. Each entry represents a different variant of the image, such as x86 and ARM64. You can view any images manifest using the docker manifest inspect command. This works with both local images and images stored on a remote registry such as Docker Hub. docker manifest inspect my-image:latest  The manifest is a list of layers included in the image. You can see the hash of the layers content and its overall size. Advertisement    If you add the --verbose flag, youll get even more information about the image. This includes the images tag (in the Ref field), its architecture, and its operating system. Docker wont load manifest details from insecure registries by default. If you need to use an improperly secured registry, add the --insecure flag to your docker manifest commands. Manifests and Multi-Arch Builds  Historically, Docker didnt support multiple image architectures. Images could only be used on machines with the same architecture as the one they were built on. This quickly proved limiting as Docker found more use in server environments and on newer ARM-based machines. Besides enabling unique identification of images, manifests facilitate multi-architecture builds. If you inspect an image that supports multiple architectures, youll see a subtly different manifest output:  docker manifest inspect php:latest  Running the command above will display the manifest for the official PHP Docker image. You can see from the screenshot that several platform options are available, including AMD64 and ARM. Weve truncated the full list which actually includes eight different supported architectures. Manifests let image authors advertise support for multiple architectures under one image tag. The Docker client selects the appropriate image version for its platform, based on the options in the list. Its expected that authors will only group images that offer identical functionality  there should be no changes beyond the target architecture or operating system. Advertisement    Each architecture in the list refers to another manifest via its digest field. The referenced manifest will be a regular single-architecture file. Docker matches the current platform to the right single-arch manifest, then loads that file to determine the final list of image layers. You can manually create multi-architecture images using the docker manifest command. Build each of the individual images and push them up to a registry. Then use the docker manifest create command to combine the images into a new shared manifest under a single tag. # on an AMD64 machine docker build -t my-image:amd64 . docker push my-image:amd64 # on an ARM machine docker build -t my-image:arm . docker push my-image:arm # now combine the manifests docker manifest create my-image:latest \ --amend my-image:x64 --amend my-image:arm docker manifest push my-image:latest  Using manifest create with the --amend flag lets you merge multiple independent manifests together. The final manifest is then pushed to Docker Hub with the latest tag. AMD64 and ARM users will both be able to create containers from this image. Manually assembling multi-arch images isnt mandatory. You can use the buildx command instead to considerably simplify the process. docker buildx build --platform linux/amd64,linux/arm64/v8 --tag my-image:latest  This single command results in an image that works on both AMD64 and ARM64 platforms. Under the hood, its still producing a multi-arch manifest list, so its helpful to understand the inner workings of how images get linked together. Annotating Manifests  Docker lets you manually override manifest data through annotations. The supported fields include architecture and operating system information. Advertisement    Use the docker manifest annotate command to setup annotations. If youre annotating a single-architecture image, supply an image tag that references it. For multi-arch images, youll need both the overall image tag and the tag of the individual manifest within the multi-arch manifest list. docker manifest annotate my-image:latest my-image:amd64 --os-version linux  This command marks the AMD64 version of the my-image:latest image as a Linux-based container. Annotations dont often need to be set by hand. Theyre usually inferred automatically from the build environment. You can use the annotate command to add missing fields or change image configuration in the future. Summary  Docker manifests describe an images layers and the architectures it supports. A manifest can be either single architecture, supporting a specific platform, or multi-architecture. In the latter case, the file contains a list of references to the single-arch manifests it incorporates.