Docker Desktop on Apple Silicon: Known Issues and x86 Emulation Fixes

Docker Desktop on an M-series Mac works great right up until you pull an image that was built for Intel. Then things get weird: containers that crash on startup, builds that take ten times longer than on your colleague’s Linux box, mysterious “exec format error” messages, and a fan that suddenly remembers it exists. If that’s why you’re here, the short answer is: your Mac is an arm64 machine, that image is amd64, and everything between the two is emulation with real costs.

We run Docker daily on M2 and M4 Macs at MacLaunch, and this page collects every issue we’ve actually hit, with the fix for each. It’s the troubleshooting companion to our Docker on Apple Silicon setup guide, so if you haven’t installed Docker yet, start there and come back when something breaks.

The core problem: amd64 images on an arm64 Mac

Apple Silicon runs the arm64 architecture. Most older Docker images (and plenty of current ones, looking at you, obscure enterprise tools) are built only for linux/amd64. When you run one of those, Docker Desktop has to emulate an Intel CPU using either Rosetta 2 or QEMU. Docker itself calls this “best effort”, which is a polite way of saying: it usually works, it’s always slower, and sometimes it just falls over.

Symptoms of running under emulation:

• A warning in your terminal: “The requested image’s platform (linux/amd64) does not match the detected host platform”
• Builds and test suites running 2x to 10x slower than native
• Random segfaults, hangs, or processes dying with no useful logs
• “exec format error” when the emulation layer isn’t available at all
• Higher memory use and noticeably worse battery life

Quick diagnosis: run docker image inspect <image> | grep Architecture. If you see amd64 on your Apple Silicon Mac, everything below applies to you.

Fix 1: Prefer native arm64 images (always)

Boring but true: the best emulation fix is not emulating. Most popular images (Postgres, Redis, Node, Python, nginx, MySQL 8+) have been multi-arch for years, so Docker pulls the arm64 variant automatically. The stragglers are usually old pinned tags, internal company images, and a few vendor tools.

• Check what’s available on Docker Hub under the image’s Tags page (look for linux/arm64 in the OS/Arch column).
• Update pinned tags. That postgres:11 from your 2021 docker-compose file has an arm64-capable successor.
• For internal images, ask whoever owns CI to publish multi-arch manifests (see the buildx section below, then send them the link).

Fix 2: Turn on Rosetta emulation, not QEMU

When you genuinely need amd64, Docker Desktop can emulate it two ways, and the difference is dramatic:

Emulation	Speed	Stability	Notes
QEMU	Slow (often 5-10x penalty)	Flaky under load	Old default; inotify file watching doesn’t work, some processes crash outright
Rosetta 2	Much faster (commonly 2-3x penalty)	Good for most workloads	Default on modern Docker Desktop; needs macOS Ventura or later and the Virtualization framework

In Docker Desktop, open Settings > General and make sure “Use Rosetta for x86_64/amd64 emulation on Apple Silicon” is enabled along with the Virtualization framework. On current Docker Desktop releases this is on by default, but we still find Macs where an old setting migrated forward with it off. If Rosetta isn’t installed yet, run softwareupdate –install-rosetta once and you’re set.

Rosetta isn’t perfect either. A few things still misbehave under it (some JIT-heavy runtimes, certain old glibc builds, the occasional fatal error that’s been bouncing around Docker’s issue tracker for years). If a specific container crashes under Rosetta, try flipping the setting off to force QEMU for a run, or better, find an arm64 build of that image.

Fix 3: Use –platform deliberately

The –platform flag tells Docker which architecture you want, per command:

• docker run –platform linux/amd64 someimage forces Intel emulation for one container
• In a Dockerfile: FROM –platform=linux/amd64 someimage (use sparingly, it hardcodes the arch for everyone)
• In docker-compose.yml: add platform: linux/amd64 under the service
• Or set DOCKER_DEFAULT_PLATFORM=linux/amd64 in your shell when a whole project needs it

Two rules of thumb from painful experience. First, only pin platforms where you must; a blanket DOCKER_DEFAULT_PLATFORM in your dotfiles will silently slow down everything you run. Second, when a teammate on Linux can’t reproduce your problem, check for a stray platform pin before you blame the code.

Fix 4: Build multi-arch images with buildx

If you build images that other people (or your amd64 CI servers) consume, build for both architectures at once:

1. Create a builder: docker buildx create –use –name multiarch
2. Build and push both variants in one shot: docker buildx build –platform linux/amd64,linux/arm64 -t you/app:latest –push .

The arm64 half builds natively and flies; the amd64 half builds under emulation and doesn’t. For anything compile-heavy, cross-compile inside the Dockerfile (Go and Rust make this easy) or split the two platforms across native runners in CI and stitch the manifest together. Your M4’s cores are quick, but emulated compilation still burns minutes you don’t need to spend.

Fix 5: File sharing performance (bind mounts)

Not an emulation problem, but it’s the other big “Docker is slow on my Mac” complaint. Containers run inside a VM, so every bind-mounted file access crosses a boundary. Docker Desktop’s VirtioFS made this far better than the old gRPC-FUSE days, and it’s the default now, but you can still help it along:

• Check Settings > General and confirm VirtioFS is selected for file sharing.
• Keep huge dependency folders out of bind mounts. The classic Node trick: mount your source, but put node_modules in a named volume. In our testing that alone can turn a 45 second install-heavy build into under 20.
• Do heavy I/O (databases, package caches) in named volumes, which live inside the VM’s native filesystem and are dramatically faster.
• Remember that inotify-style file watching is unreliable under QEMU emulation; if hot reload isn’t firing, use your tool’s polling mode or switch that container to arm64.

Fix 6: Memory, CPU, and networking quirks

• Memory: Docker Desktop’s VM gets a fixed slice of RAM (Settings > Resources). Emulated containers use more memory than native ones, so if amd64 containers are getting OOM-killed, bump the VM allocation before you blame the app. On a 16GB Mac, 6-8GB for Docker is a sane ceiling.
• Networking: there’s no docker0 bridge you can reach from macOS. Use host.docker.internal to reach your Mac from a container, and published ports (-p) to reach containers from your Mac. Tools that assume Linux-style direct container IP access won’t work.
• Ports that won’t bind: macOS services (AirPlay Receiver loves port 5000 and 7000) silently occupy ports. If a container can’t bind, run lsof -i :5000 and check System Settings before restarting Docker.
• VPNs: corporate VPN clients occasionally break the VM’s DNS. Toggling the VPN or setting explicit DNS in Docker’s settings usually sorts it.

Honest alternatives: OrbStack, Colima, Podman

Docker Desktop has improved a lot on Apple Silicon, but it’s not your only option, and we’d be lying if we said we never use the others:

• OrbStack: the one we reach for most. Dramatically lighter on memory and battery, fast file sharing, near-instant startup, and it’s a drop-in replacement for the docker CLI. Free for personal use, paid for commercial. The catch: it’s a smaller company than Docker, which matters to some teams.
• Colima: free and open source, runs Docker in a lightweight VM via the command line. Great if you don’t want a GUI or a license conversation. You’ll do a bit more configuration yourself (make sure you set the mount type to virtiofs, the default SSHFS mounts are painfully slow).
• Podman: Red Hat’s daemonless engine, mostly Docker-compatible, nice rootless security story. Compose support has matured, but you’ll still hit occasional compatibility edges with tooling that assumes real Docker.

If Docker Desktop is working for you, there’s no urgent reason to switch. If your complaint is resource usage or licensing cost, OrbStack or Colima will probably make you happy. Either way, the amd64 vs arm64 fundamentals in this article apply identically to all of them.

Containers are usually one part of a bigger development setup on a Mac. If you’re building for Apple’s platforms too, our guide to building iOS and Mac apps covers the Xcode side, and the new macOS app development guide goes deep on Mac-specific tooling.

FAQ

Why is Docker so slow on my M1/M2/M3/M4 Mac?

Nine times out of ten it’s one of two things: you’re running amd64 images under emulation (check with docker image inspect), or you’re bind-mounting a huge directory and paying the VM file-sharing tax. Switch to arm64 images, enable Rosetta emulation for the stragglers, and move heavy folders into named volumes.

Should I force everything to linux/amd64 to match production?

No. Run arm64 locally for speed and let CI build/test the amd64 artifacts. True architecture-specific bugs are rare in interpreted languages and well-maintained runtimes. Pin amd64 only for the specific containers that genuinely need it (some proprietary binaries, certain database extensions).

Does Rosetta 2 work for all x86 containers?

Most, not all. Rosetta covers the common cases well, but a few workloads (unusual syscalls, some JIT compilers, very old binaries) still crash or misbehave. When that happens, try QEMU as a fallback or hunt down an arm64 build. Filesystem event notifications also remain unreliable under QEMU, which breaks hot-reload workflows.

Is OrbStack actually better than Docker Desktop?

For day-to-day dev on Apple Silicon, in our experience, yes: faster startup, better battery, quicker bind mounts. But Docker Desktop has closed a lot of the gap with VirtioFS and Rosetta support, and it’s the safer default in large orgs with existing Docker licenses and support contracts.