How to Use Docker Manifest: Syntax, Example, and Tips

Use docker manifest commands to create, inspect, and push multi-architecture image lists. Start by creating a manifest list with docker manifest create, then annotate and push it to a registry with docker manifest push.

Syntax

The docker manifest command manages multi-architecture image lists. Key subcommands include:

• create: Make a new manifest list from existing images.
• annotate: Add metadata like architecture or OS to images in the list.
• push: Upload the manifest list to a Docker registry.
• inspect: View details of a manifest list.

Basic syntax:

docker manifest create <manifest-name> <image1> <image2> ...
docker manifest annotate <manifest-name> <image> --arch <arch> --os <os>
docker manifest push <manifest-name>
docker manifest inspect <manifest-name>

bash

docker manifest create myapp:latest myapp:amd64 myapp:arm64
docker manifest annotate myapp:latest myapp:arm64 --arch arm64 --os linux
docker manifest push myapp:latest
docker manifest inspect myapp:latest

Example

This example creates a manifest list named myapp:latest combining two images for amd64 and arm64 architectures, annotates the arm64 image, pushes the manifest to the registry, and inspects it.

bash

docker manifest create myapp:latest myapp:amd64 myapp:arm64

docker manifest annotate myapp:latest myapp:arm64 --arch arm64 --os linux

docker manifest push myapp:latest

docker manifest inspect myapp:latest

Output

{
  "schemaVersion": 2,
  "mediaType": "application/vnd.docker.distribution.manifest.list.v2+json",
  "manifests": [
    {
      "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
      "size": 1234,
      "digest": "sha256:abcdef...",
      "platform": {
        "architecture": "amd64",
        "os": "linux"
      }
    },
    {
      "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
      "size": 1234,
      "digest": "sha256:123456...",
      "platform": {
        "architecture": "arm64",
        "os": "linux"
      }
    }
  ]
}

Common Pitfalls

• Forgetting to annotate images can cause wrong architecture info in the manifest.
• Trying to create a manifest with images not pushed to the registry will fail.
• Using docker manifest requires Docker CLI experimental features enabled in some versions.
• Not pushing individual images before creating the manifest causes errors.

bash

Wrong way:
docker manifest create myapp:latest myapp:amd64 myapp:arm64
# Missing annotation for arm64

docker manifest push myapp:latest

Right way:
docker manifest create myapp:latest myapp:amd64 myapp:arm64
docker manifest annotate myapp:latest myapp:arm64 --arch arm64 --os linux
docker manifest push myapp:latest

Quick Reference

Command	Description
docker manifest create	Create a manifest list from images
docker manifest annotate --arch --os	Add platform info to an image in the manifest
docker manifest push	Push the manifest list to a registry
docker manifest inspect	Show details of a manifest list

Key Takeaways

Use docker manifest to combine images for multiple architectures into one reference.

Always annotate images with correct architecture and OS before pushing the manifest.

Push individual images to the registry before creating the manifest list.

Inspect manifests to verify the included images and platforms.

Enable Docker CLI experimental features if docker manifest commands are unavailable.