An image may need different builds for different operating systems and CPU architectures. If a registry has no variant matching your Docker Engine, the pull can fail before a container starts. A manifest list lets one image tag point to the available platform-specific variants. section 12.1 section 12.3
Each image variant has its own manifest. The manifest list groups those manifests under the tag used for the multi-platform image. Inspect a published tag with docker manifest inspect diamol/base:2e; its output includes each variant’s digest, OS, and CPU architecture. The command also works for single-platform images. section 12.3
To publish a list manually:
- Build and push platform-specific images, using tags that identify their OS and CPU. section 12.3
- Create a manifest list named with the shared image tag and include the variant tags. section 12.3
- Push the list, then check that Docker Hub shows the variants beneath that tag. section 12.3
# create a manifest list with a name # followed by all the tags it contains: docker manifest create "$dockerId/ch12-folder-list:2e" ` "$dockerId/ch12-folder-list:2e-linux-amd64" ` "$dockerId/ch12-folder-list:2e-linux-arm64" ` "$dockerId/ch12-folder-list:2e-linux-arm" # push the manifest to Docker Hub: docker manifest push "$dockerId/ch12-folder-list:2e" # now browse to your page on Docker Hub and check the image
Commands for creating and pushing a Linux manifest list after its amd64, arm64, and arm images have been pushed. Set dockerId to your Docker Hub ID first. section 12.3
Buildx offers a shorter route: given builder nodes for the requested architectures and a Dockerfile whose images support them, docker buildx build --platform linux/arm64,linux/amd64 --push builds the variants and publishes the manifest list. Unlike the manual approach, the resulting Docker Hub image need not expose separate tags for every variant. section 12.4
Try it in CI
For an app with three components, create and push one manifest list per component to GHCR. Include Linux and Windows AMD64 variants, take image references from Compose files, test the script locally, then run it in a GitHub Actions workflow. section 16.6
