Docker Official Images are now Multi-platform

Sep 19 2017

This past week, Docker rolled out a big update to our Official Images to make them multi-platform aware. Now, when you run docker run hello-world, Docker CE and EE will pull and run the correct hello-world image whether that’s for x86-64 Linux, Windows, ARM, IBM Z mainframes or any other system where Docker runs. With Docker rapidly adding support for additional operating systems (like Windows) and CPU architectures (like IBM Z) this is an important UX improvement.

Docker Official Images are a curated set of container images that include:

The official images have always been available for x86-64 Linux. Images for non x86 Linux architectures have also been available, but to be fetched either from a different namespace (docker pull s390x/golang on IBM Z mainframe) or using a different tag (docker pull golang:nanoserver on Windows). This was not the seamless and portable experience that we wanted for users of Docker’s new multi-arch and and multi-os orchestration features.

Luckily the Docker registry and distribution protocol have supported multi-platform images since Docker 1.10, using a technology called manifest lists. A manifest list can take the place of a single-architecture image manifest in a registry (for example for golang) and contains a list of (“platform”, “manifest-reference”) tuples. If a registry responds to a docker pull command with a registry list instead of an image manifest, Docker examines the manifest list and then pull the correct list entry for the platform that it happens to be running on.

The distribution protocol is backwards compatible, and manifest lists are only served to clients that indicate support in the Accept header. For clients that don’t support manifest lists, registries will fall back to the x86-64 Linux image manifest. Manifest lists are fully supported by Docker Content Trust to ensure that multi-platform image content is cryptographically signed and verified.

Manifest lists have been rolled out for Linux images for most CPU architectures, and Windows support is also getting there. If your favorite CPU architecture or OS isn’t covered yet, you can always continue to use a CPU or OS-specific tag or image when pulling. Fetching images by digest is also unaffected by this update.

If you’re interested in building multi-arch images, check out Phil Estes’ manifest-list tool and keep track of the PR to add a manifest command to the Docker CLI.

Manifest lists and multi-arch Docker images have been in the works for a long time. We’re excited that these features are now making it simpler to pull and use Docker Official Repo images seamlessly on the many platforms where Docker is available.




3 thoughts on “Docker Official Images are now Multi-platform

  1. Hi Michael,

    great news but as Docker beginner I really miss a row in "docker search" command output which tells me for which CPU architecture not only an official image was created.
    Would it be possible to add a row named "platform" for which image maintainers could add information listing the supported CPU architecture?

    Best regards

    (Posted again with notifocation enabled)

  2. Please notify

  3. This is a great move in the correct direction, soon I hope, all Images will be multi-platform aware not just Official Images.

Leave a Reply