What happens when you try to pull the following MySQL Docker image on your Apple MacBook M1 Pro laptop?

 docker pull mysql:8.0.23

You might encounter the following error message:

8.0.23: Pulling from library/mysql
no matching manifest for linux/arm64/v8 in the manifest list entries

The same command might work on the Cloud instance or on your colleague's laptop. It's weird, isn't it?

Let's deep dive further

The mquery tool allows you to query any public image in any public container repository as to its media type (standard OCIv1 or Docker v2.2 image), digest, and platform support, if it is an OCI index or Docker v2.2 manifest list. This image is created and pushed by a GitHub Action when any release occurs in the public GitHub repository estesp/mquery.

Let us try to run mquery tool against the mysql:8.0.23 and verify the result:

docker run --rm mplatform/mquery mysql:8.0.23                 
Unable to find image 'mplatform/mquery:latest' locally
latest: Pulling from mplatform/mquery
894bcacb16df: Pull complete 
a0c6ee298a93: Pull complete 
Digest: sha256:d0989420b6f0d2b929fd9355f15c767f62d0e9a72cdf999d1eb16e6073782c71
Status: Downloaded newer image for mplatform/mquery:latest
Image: mysql:8.0.23 (digest: sha256:6e0014cdd88092545557dee5e9eb7e1a3c84c9a14ad2418d5f2231e930967a38)
 * Manifest List: Yes (Image type: application/vnd.docker.distribution.manifest.list.v2+json)
 * Supported platforms:
   - linux/amd64

As you can see above, the Docker image has limited support only for x86 platform(missing Arm arch support)

Your CPU can only run binaries for its native architecture. For example, Docker images built for an x86 system can’t run on an Arm-based system. With Apple fully transitioning to their custom Arm-based silicon, it’s possible that your x86 (Intel or AMD) Docker Image won’t work with Apple’s recent M-series chips. Consequently, we always recommended building multi-arch container images. Below is the mplatform/mquery Docker image that lets you query the multi-platform status of any public image, in any public registry:

docker run --rm mplatform/mquery eclipse-temurin:17-jre-alpine
Image: eclipse-temurin:17-jre-alpine (digest: sha256:ac423a0315c490d3bc1444901d96eea7013e838bcf7cc09978cf84332d7afc76)
 * Manifest List: Yes (Image type: application/vnd.docker.distribution.manifest.list.v2+json)
 * Supported platforms:
   - linux/amd64

Docker introduced the docker buildx command to help you build multi-architecture images. Buildx is a Docker component that enables many powerful build features with a familiar Docker user experience. All builds executed via Buildx run via the Moby BuildKit builder engine. BuildKit is designed to excel at multi-platform builds, or those not just targeting the user’s local platform. When you invoke a build, you can set the --platform flag to specify the build output’s target platform, (like linux/amd64, linux/arm64, or darwin/amd64):

docker buildx build --platform linux/amd64, linux/arm64 -t mysql:8.0.23 .

Leverage multi-CPU architecture support

Docker images can support multiple architectures, which means that a single image may contain variants for different architectures, and sometimes for different operating systems, such as Windows.

When running an image with multi-architecture support, docker automatically selects the image variant that matches your OS and architecture.

Most of the Docker Official Images on Docker Hub provide a variety of architectures. For example, the busybox image supports amd64, arm32v5, arm32v6, arm32v7, arm64v8, i386, ppc64le, and s390x. When running this image on an x86_64 / amd64 machine, the amd64 variant is pulled and run.

You can even now run ARM or Intel Docker containers on the Apple M1 Mac with Docker Desktop for Mac M1. The default, of course, is to run the ARM version but if you use the --platform linux/amd64 parameter Docker will run the Intel version for you.

Interesting, isn't it?

Getting Help

Have a question about Docker Desktop? Search the Docker Forum Docker Desktop tag for answers, or post a question in our Docker Community Forum.