Multi-Architecture Images

docker buildx (Preferred)

This is the preferred way to build images, and can be completed on a single host with binfmt support correctly installed.



if ! docker buildx inspect builder; then
    docker buildx create --name builder --driver docker-container --node default --platform "${platform_list}"
docker buildx use builder

docker buildx build . --push --tag "${tag}" --platform "${platform_list}"

docker manifest

Multi-architecute images are created using the docker manifest command, which is currently experimental. See Enable Experimental Features.


Create and Push the Manifest

# build or pull images
docker pull ${IMAGE_REPO}:${IMAGE_TAG}-${ARCH1}
docker pull ${IMAGE_REPO}:${IMAGE_TAG}-${ARCH2}

# create the manifest
docker manifest create ${IMAGE_REPO}:${IMAGE_TAG} \

# annotate the manifest with os / architecture requirements
# NOTE: this should not be necessary
#docker manifest annotate ${IMAGE_REPO}:${IMAGE_TAG} \
#  --os linux --arch amd64
#docker manifest annotate ${IMAGE_REPO}:${IMAGE_TAG} \
#  --os linux --arch arm

# inspect the manifest to check it's correct
docker manifest inspect ${IMAGE_REPO}:${IMAGE_TAG}

# push the manifest as :${IMAGE_TAG}
docker manifest push ${IMAGE_REPO}:${IMAGE_TAG}

# also push as :latest...
mv ~/.docker/manifests/${IMAGE_REPO//\//_}-{${IMAGE_TAG},latest}
docker manifest push --purge ${IMAGE_REPO}:latest


There is currently no way to tag this manifest and re-use it, for example pushing both a v1 and latest image. The whole process must be completed for each tag.


There is currently no way to remove a manifest via the CLI... but:

  • You can use docker manifest push --purge
  • The files are stored in ~/.docker/manifests/

Use the Image

docker run --rm -it ${IMAGE_REPO}:${IMAGE_TAG}