Running amd64 Docker images on Apple Silicon (M1–M4)

Why Docker warns that linux/amd64 doesn't match linux/arm64/v8 on an M1–M4 Mac, how to run amd64 images with --platform, Rosetta or QEMU, and how to build images for both.

Running amd64 Docker images on Apple Silicon works: an M1, M2, M3 or M4 Mac runs linux/amd64 containers by translating their x86-64 code to arm64 as it runs. Pass --platform linux/amd64 (or set it in Compose), make sure your engine uses Rosetta rather than QEMU for the translation, and most images just work, a little slower than native. The rest of this post explains the warning you probably came here with, what Docker decides when it pulls, and how to stop needing emulation at all by building images for both architectures.

New to some of the terms? Our basics cover image layers and registries.

“The requested image’s platform (linux/amd64) does not match the detected host platform”

This is the line most people search for:

WARNING: The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8) and no specific platform was requested

It’s a warning, not an error. It means three things at once:

  • Your Mac’s Linux VM is arm64 (linux/arm64/v8), because Apple silicon is an Arm chip.
  • The image you asked for only had an amd64 build, so that’s what you got.
  • You didn’t say --platform, so Docker is pointing out that the container will run under emulation.

If the container then works, you can silence the warning by asking for amd64 on purpose (next sections). If it fails with exec format error, there’s no emulator registered in the VM at all, and the engine can’t run x86-64 programs; turning on Rosetta in your engine fixes that.

What a platform is, and how a pull picks one

A platform is an operating system plus a CPU architecture, written os/arch[/variant]: linux/amd64, linux/arm64/v8, linux/arm/v7.

Most popular images are published for several platforms under one tag. The registry stores them as an index (also called a manifest list): one entry per platform, each pointing at its own manifest and layers. When you pull, the client asks for the tag, gets the index, and picks the entry for its machine. Our registries post walks through a pull step by step.

One socket, three ways in: what happens when you docker run on an M1 to M4 Mac, drawn as plugs and adapters. On the left, the index for alpine:latest has one entry per platform: linux/arm64/v8, which matches the Mac; linux/amd64, used when it is the only build or you pass --platform; and linux/arm/v7, which is skipped. On the right is the arm64 socket, your Mac's Linux VM, linux/arm64/v8 on Apple silicon. The arm64 plug goes straight in: native, full speed, nothing to translate. An amd64 plug has a different shape and needs an adapter. Adapter one is Rosetta for Linux: shared into the VM by macOS, close to native speed, handles AVX and AVX2 but not AVX-512. Adapter two is QEMU user mode: much slower for heavy work, no ptrace so strace and gdb fail, and no namespace flags on clone. With no adapter registered, the amd64 plug doesn't fit and the container fails with exec format error. Footer: see the plugs with docker buildx imagetools inspect alpine; pick one with --platform linux/amd64.

To see which platforms an image actually has, ask the registry without pulling anything:

docker buildx imagetools inspect alpine
Manifests:
  Name:      docker.io/library/alpine:latest@sha256:…
  MediaType: application/vnd.docker.distribution.manifest.v2+json
  Platform:  linux/amd64
  ...
  Platform:  linux/arm64/v8

Docker’s imagetools inspect reference shows the full output for alpine, which is built for seven platforms. If your image lists only linux/amd64, every Apple silicon Mac will run it under emulation. To check what you have locally after a pull:

docker image inspect -f '{{.Os}}/{{.Architecture}}' alpine
docker run --rm alpine uname -m      # aarch64 = native, x86_64 = emulated

Asking for amd64 on purpose

On one command: --platform

docker pull --platform linux/amd64 postgres:16
docker run --rm --platform linux/amd64 alpine uname -m
# x86_64

--platform works on pull, run, create and build. Use it when an image has both builds and you need the amd64 one, for example to reproduce a bug that only shows up on your x86 servers.

For a whole shell: DOCKER_DEFAULT_PLATFORM

export DOCKER_DEFAULT_PLATFORM=linux/amd64

Docker’s CLI reference describes it as the “default platform for commands that take the --platform flag” (environment variables). It’s handy for a session where everything must be amd64. Don’t put it in your shell profile: every image you pull, including ones with perfectly good arm64 builds, will then run emulated.

For one service in Compose: platform:

services:
  legacy-api:
    image: example/legacy-api:2.3
    platform: linux/amd64
  db:
    image: postgres:16      # has arm64, stays native

The Compose spec says platform “defines the target platform the containers for the service run on” using os[/arch[/variant]] (Compose file reference). Setting it per service is better than the environment variable, because only the service that needs amd64 pays for emulation. More on Compose without Docker Desktop in Docker Compose on a Mac without Docker Desktop.

Rosetta vs QEMU: speed and correctness

Your Mac can’t run x86-64 code directly, so something inside the Linux VM has to translate it. The VM’s kernel spots an x86-64 program through binfmt_misc and hands it to whichever translator is registered. On a Mac there are two candidates.

Rosetta for Linux

Apple’s Virtualization framework can share Rosetta into an arm64 Linux VM. Apple’s documentation says this has worked since macOS 13, runs “Intel apps that run in an ARM Linux distribution”, and, from macOS 14, supports ahead-of-time caching that “can improve the performance of some X86 workloads” (Running Intel Binaries in Linux VMs).

  • Speed: Docker called Rosetta’s x86-64 performance “nearly on par with native execution” when it made the feature generally available in Docker Desktop 4.25 (Docker blog).
  • Correctness: Rosetta “translates all x86_64 instructions, including ones from the AVX and AVX2 instruction set, but it doesn’t support running AVX512 vector instructions” (About the Rosetta translation environment). Software that assumes AVX-512 without checking will crash.
  • Installing it: on macOS 26 and earlier, Rosetta has to be installed (softwareupdate --install-rosetta). Apple says that starting in macOS 27, “support for Intel binary translation for Linux apps is included in macOS”, with nothing to install.

QEMU user-mode emulation

QEMU is the general-purpose emulator engines fall back to when Rosetta isn’t available or isn’t switched on. It works on any host, but:

  • Speed: Docker’s own docs warn that “emulation with QEMU can be much slower than native builds”, “especially for compute-heavy tasks like compilation and compression or decompression” (multi-platform builds).
  • Correctness: QEMU’s user-mode docs list gaps that matter in containers: ptrace isn’t implemented, so strace and gdb don’t work on emulated programs; clone flags that affect namespaces “are not supported”; and “differences between the host and guest memory models can cause issues” for software that relies on a particular memory model (QEMU user mode).

In practice: if amd64 containers are painfully slow, or a JVM, database or debugger misbehaves only on your Mac, check which translator your engine uses before anything else.

Turning Rosetta on

  • Docker Desktop: Settings → General → “Use Rosetta for x86_64/amd64 emulation on Apple Silicon”. Docker’s settings page notes it’s “available with the Apple Virtualization framework VMM” (Docker Desktop settings).
  • Other engines have their own switch; check the engine’s docs. Docker Desktop alternatives compared covers the main ones.

Build multi-arch images with buildx, and skip emulation

The real fix for your own images is to publish both builds under one tag. Then every Mac pulls arm64 and every x86 server pulls amd64, and nobody emulates anything at run time.

docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t ghcr.io/you/app:1.4 \
  --push .

That’s Docker’s documented command for a two-platform build (multi-platform builds), plus a tag and --push. A few things to know:

  • Where the result goes. A multi-platform result needs an image store that can hold an index. Docker says Docker Desktop and Docker Engine 29.0+ use the containerd image store by default, which supports it; with a docker-container builder, the images aren’t loaded into the engine’s store, so push them to a registry instead.
  • Building the other architecture still emulates. Building linux/amd64 on your Mac runs the Dockerfile’s RUN steps under Rosetta or QEMU. For compiled languages, cross-compiling in a native stage (Go’s GOARCH, Rust targets) is usually much faster than emulating the compiler.
  • Check the result with docker buildx imagetools inspect ghcr.io/you/app:1.4. You should see both linux/amd64 and linux/arm64.

For third-party images that only ship amd64, check the project’s releases for a newer tag with arm64 before reaching for --platform.

How Kiri handles amd64 images

Kiri is an open-source container engine whose Mac app runs Docker commands in a small arm64 Linux VM. According to its docs:

  • amd64 runs through Rosetta. macOS shares Rosetta for Linux into the VM over virtiofs, and the VM’s kernel hands every x86-64 program to it through binfmt_misc. There’s nothing to set per image. On macOS versions that need it, install Rosetta with softwareupdate --install-rosetta.
  • --platform is honoured on docker pull and docker run.
  • Without --platform, it pulls arm64. If an image has no arm64 build but has an amd64 one, and Rosetta is installed, Kiri pulls amd64 and says so: … has no linux/arm64 image; using linux/amd64 through Rosetta.
  • One platform per tag. Kiri keeps one variant of each tag, so pulling alpine for linux/amd64 replaces the arm64 alpine you had, and a later run that asks for the other platform pulls again.
docker pull -q --platform linux/amd64 alpine
docker image inspect -f '{{.Os}}/{{.Architecture}}' alpine   # linux/amd64
docker run --rm alpine uname -m                               # x86_64

The Docker for Mac page has the rest of the Mac story, and Kiri vs Docker Desktop compares the two side by side. If you’re moving over, see switching from Docker Desktop, or download Kiri.

In short

  • The platform mismatch warning means you got an amd64 image on an arm64 Mac and it will run emulated. It’s not an error.
  • docker buildx imagetools inspect <image> lists the platforms an image really has, straight from the registry.
  • Ask for amd64 with --platform linux/amd64, DOCKER_DEFAULT_PLATFORM for a shell, or platform: per Compose service.
  • Rosetta runs close to native speed and handles AVX and AVX2, not AVX-512. QEMU is much slower for heavy work and has no ptrace.
  • exec format error means no translator is registered: turn on Rosetta in your engine.
  • For your own images, build both with buildx and push one tag, so nobody has to emulate.