podman manifest: Multi-Arch Image Lists
podman manifest creates and pushes a manifest list so one tag serves multiple CPU architectures.
To ship one image that runs on amd64 and arm64, build per-arch images, group them into a manifest list, and push the list. podman manifest is how you assemble it.
What it does
podman manifest creates an image index (manifest list) and adds per-architecture images to it. Pushing the list with --all uploads every referenced image, so the registry returns the right one per client architecture. podman build --manifest can do this in one step.
Common usage
podman manifest create myapp:latest
podman build --platform linux/amd64 -t myapp-amd64 .
podman build --platform linux/arm64 -t myapp-arm64 .
podman manifest add myapp:latest containers-storage:myapp-amd64
podman manifest add myapp:latest containers-storage:myapp-arm64
podman manifest push --all myapp:latest ghcr.io/owner/app:latestOptions
| Command/Flag | What it does |
|---|---|
| create <name> | Create an empty manifest list |
| add <list> <image> | Add a per-arch image to the list |
| push --all <list> <dest> | Push the list and all referenced images |
| inspect <list> | Show the contents of a manifest list |
| --arch / --os | Override the platform when adding |
In CI
For arm64 on an amd64 runner, register QEMU/binfmt (for example the multiarch/qemu-user-static image) so --platform linux/arm64 can emulate the build. Always push with --all or the registry gets a list referencing images it does not have.
Common errors in CI
"manifest unknown" after a push means you pushed the list without --all, so the per-arch images are missing; re-push with --all. "exec format error" or "exec user process caused: exec format error" during an emulated arm64 build means binfmt/QEMU is not registered. "image not known" on manifest add means the per-arch tag does not exist locally; build it first.