Docker "No Matching Manifest for linux/amd64" on M1/M2 Mac

This error means the specific image (and tag) you're trying to pull doesn't have a build published for ARM64, the CPU architecture Apple Silicon Macs (M1, M2, M3) actually use — Docker correctly refuses to silently run an incompatible architecture, rather than pretending compatibility that doesn't exist.

The Problem

Pulling or running an image on an Apple Silicon Mac fails with:

no matching manifest for linux/amd64/v8 in the manifest list entries

ERROR: failed to solve: no match for platform in manifest: not found

The exact same docker-compose.yml or Dockerfile might work fine on an Intel Mac, a Linux machine, or in CI, pointing specifically at the architecture mismatch as the cause.

Why It Happens

Modern Docker images are often published as "multi-arch" — a single image tag actually points to a manifest list containing separate builds for different CPU architectures (linux/amd64 for Intel/AMD, linux/arm64 for Apple Silicon and other ARM-based systems), and Docker automatically pulls whichever variant matches your machine. This error means the specific image and tag genuinely doesn't include an ARM64 variant at all — common with:

• Older or less actively maintained images that were published before ARM64 support was common, and haven't been updated to include a matching build
• Internal, private, or self-built images that were only ever built for amd64, since the build pipeline never targeted ARM64 as an output
• Certain specialized or niche images where the maintainer simply hasn't prioritized ARM64 support, even if the underlying software itself would technically run fine on ARM

The Fix

First, confirm whether an ARM64 variant genuinely exists for the image by checking its available tags/platforms on Docker Hub or wherever it's hosted — many popular images do support ARM64 under the same tag, and the error might be resolvable simply by ensuring you're pulling the correct, current tag rather than an outdated pinned version that predates ARM64 support.

If no native ARM64 build exists, force Docker to run the AMD64 version using emulation via Rosetta 2 (built into Docker Desktop on Apple Silicon) — this works for most images, though with some performance overhead compared to running natively:

docker run --platform linux/amd64 your-image

In Docker Compose:

services:
  app:
    image: your-image
    platform: linux/amd64

This explicitly tells Docker to pull and run the AMD64 variant even though your machine is ARM64, relying on Docker Desktop's built-in emulation layer to translate the instructions — functional for most workloads, though noticeably slower for CPU-intensive operations compared to a genuinely native ARM64 build.

Confirm Rosetta 2 emulation is actually enabled in Docker Desktop's settings, since some versions require this to be explicitly turned on rather than assuming it or having it on by default:

# Docker Desktop > Settings > General >
# "Use Rosetta for x86/amd64 emulation on Apple Silicon"

If you're building your own image from a Dockerfile rather than pulling a third-party one, build multi-arch images yourself using buildx, producing both AMD64 and ARM64 variants so the same image tag works natively on either architecture without needing emulation at all:

docker buildx build --platform linux/amd64,linux/arm64 -t your-registry/your-image:latest --push .

This requires buildx (included in modern Docker installations) and pushes directly to a registry, since building genuinely multi-platform images typically can't be done purely locally without also pushing — the local Docker daemon can only load a single-platform image at a time into its local image store.

Still Not Working?

If emulation via --platform linux/amd64 works but performance is unacceptably slow for your specific workload (particularly noticeable with compute-heavy applications, or certain database engines under emulation), check whether a community-maintained ARM64-compatible fork or alternative image exists for the same software — for popular but slow-to-officially-support-ARM64 images, it's common for the community to maintain unofficial multi-arch builds that provide genuinely native ARM64 performance while the official image maintainer hasn't yet added that support themselves.