docker buildx imagetools: Inspect and Create Manifests
docker buildx imagetools inspects an image manifest and creates or re-tags manifest lists directly on the registry, without pulling the image locally.
buildx imagetools is the built-in way to look at a multi-arch image and to combine or re-tag manifests, operating on the registry so nothing is pulled to disk.
What it does
docker buildx imagetools inspect fetches and prints an image manifest or index (with --raw for the raw JSON). docker buildx imagetools create builds a new manifest list from existing references (or copies/re-tags one) and pushes it, all without pulling image content locally.
Common usage
# inspect an image and its platforms
docker buildx imagetools inspect ghcr.io/acme/app:1.4.0
# raw index JSON
docker buildx imagetools inspect --raw ghcr.io/acme/app:1.4.0
# create a multi-arch tag from per-arch images
docker buildx imagetools create -t ghcr.io/acme/app:1.4.0 \
ghcr.io/acme/app:1.4.0-amd64 ghcr.io/acme/app:1.4.0-arm64
# re-tag without pulling
docker buildx imagetools create -t ghcr.io/acme/app:stable ghcr.io/acme/app:1.4.0Options
| Flag | What it does |
|---|---|
| inspect <ref> | Print the manifest / index for a reference |
| inspect --raw | Print the raw manifest JSON |
| inspect --format <tmpl> | Go-template output (e.g. config, SBOM, provenance) |
| create -t <ref> | Target tag for the new manifest list |
| create <src...> | Source references to combine into the list |
| create --append | Add sources to an existing list instead of replacing |
In CI
After a matrix build pushes per-arch images, imagetools create -t app:tag app:tag-amd64 app:tag-arm64 publishes the multi-arch tag without pulling anything. imagetools create -t new old re-tags on the registry with no pull/push cycle. It needs the docker CLI with buildx but not a running build.
Common errors in CI
"docker: 'buildx' is not a docker command" means the buildx plugin is not installed on the runner. "no such manifest" for a source means that per-arch tag was not pushed. "failed to copy: ... unauthorized" means log in to the destination registry. If inspect --format prints nothing, the requested field (for example provenance) was not attached to that image.