How to enable and build multi-platform images in Docker Desktop for Mac

gist-mac-docker-desktop-multi-platform-images.md

Enabling and Building Multi-Platform Images in Docker Desktop for Mac

🏫 To learn what multi-platform images are, see this post from Docker Multi-arch build and images, the simple way

You can use Docker Desktop for Mac to build and push multi-platform images to support your containers running on different CPU architectures like Intel/amd64 and Apple Silicon/arm64.

This post shows you how. Specifically this shows you how to...

1. Enable Building Multiple Multi-Platform Images at Once
2. Build and Push Multi-Platform Images (including multiple at once)

🙇 I learned this out of necessity from this excellent post How to build x86 (and others!) Docker images on an M1 Mac

Background

On more recent versions of Docker Desktop, by default you can only build one platform (image) at a time, for example...

docker buildx build --platform linux/arm64 .

But if you try to build more than one platform at a time, for instance...

docker buildx build --platform linux/amd64,linux/arm64 .

You'll likely encounter an error that looks something like this...

ERROR: Multiple platforms feature is currently not supported for docker driver. Please switch to a different driver (eg. "docker buildx create --use")

But, you can enable building multiple platform images at once with the docker buildx create --use command as the error suggests. This will then enable qemu-static which is already in the Docker Desktop VM.

📖 From the Docker documentation...

• docker buildx

---

Enable Building Multiple Multi-Platform Images at Once

⚙️ On older versions of Docker Desktop for Mac, you may have to enable the Docker buildx feature under Preferences > Experimental Features

To enable building multiple multi-platform images at once...

1. Verify that you have the docker buildx command and list the current builder instances...

   docker buildx ls
   

2. Enable multiple multi-platform builds with the docker buildx create command...

   docker buildx create --use
   

3. Verify that you have added a builder by again listing the builder instances...

   docker buildx ls
   

   You should see an additional builder in the output and now be able to build multiple platforms at once.

📖 From the Docker documentation...

• docker buildx
• docker buildx ls
• docker buildx create

---

Build and Push Multiple Multi-Platform Images at Once

Once you have enabled the ability to build multiple multi-platform images at once, you can build and push them.

Build

You can use the docker buildx build --platform command to build one or multiple platforms at one time:

docker buildx build --platform {-comma-separated-list-of-platforms-} .

Push

🔒 You will need to be logged into your container registry (e.g. Docker Hub) to push your images

You can use the --push option with the docker buildx build --platform command to push your single or multiple images when you build them:

docker buildx build \
--push \
--platform {-comma-separated-list-of-platforms-} \
--tag {-user/image-repository-name-}:{-image-tag-} .

Here's an example for supporting Intel CI and Production (linux/amd64) and Apple Silicon for development (linux/arm64)...

docker buildx build --no-cache --push --platform linux/amd64,linux/arm64 --tag simonjuser/bestappever:test123 .

📖 From the Docker documentation...

• docker buildx build

---