Fixing 'no matching manifest for linux/arm64/v8' on Apple Silicon (M1/M2/M3)

Why this happensSwitching to an M1, M2, or M3 Mac is usually a massive upgrade until you try to run an older Docker stack. You might try to pull a familiar image—like MySQL 5.7 or an older Python build—only to see the process hang and fail with this error:

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

The root cause is an architecture mismatch. Apple Silicon uses the ARM64 architecture, while older Docker images were often built strictly for x86_64 (Intel/AMD). When you request an image, Docker Desktop searches the registry for a version that matches your native chip. If the maintainer hasn't published an ARM64 build, Docker simply gives up.

The Quick Fix: Force the Platform via CLIYou can bypass this error by explicitly telling Docker to use the Intel version of the image. macOS handles the heavy lifting via Rosetta 2, which translates Intel instructions for your ARM chip on the fly. It is not as fast as native code, but it gets the job done.

To pull an incompatible image, add the --platform flag to your command:

# Example: Pulling MySQL 5.7, which lacks native ARM support
docker pull --platform linux/amd64 mysql:5.7

When you are ready to start the container, you must specify the platform again to ensure the emulation layer stays active:

docker run -d --name my-db --platform linux/amd64 -e MYSQL_ROOT_PASSWORD=pass mysql:5.7

The Permanent Fix: Update Docker ComposeManually typing flags is tedious, especially in a team environment where colleagues might still be using Intel-based Macs. You can automate this by baking the platform requirement directly into your docker-compose.yml file.

Simply add the platform: linux/amd64 attribute to the specific service:

services:
  db:
    image: mysql:5.7
    platform: linux/amd64
    environment:
      - MYSQL_ROOT_PASSWORD=root
    ports:
      - "3306:3306"

This configuration ensures that every team member pulls the same version. Docker Compose will automatically use the amd64 image regardless of whether the host machine is a MacBook Pro M3 or an older Intel iMac.

Better Long-Term AlternativesWhile emulation via Rosetta 2 is convenient, it comes with a performance tax. Emulated containers typically see a 20% to 35% hit in CPU performance and higher battery drain. Whenever possible, switch to images that support ARM64 natively.

• MySQL: Upgrade to mysql:8.0 or switch to mariadb:latest, both of which have excellent ARM support.
• Postgres: Versions 13 and newer are fully optimized for ARM64.
• Development Runtimes: Use -slim or -alpine tags for Node.js and Python. These are almost always multi-architecture. Before you commit to a legacy image, check its "OS/ARCH" section on Docker Hub. If you don't see arm64 listed, you will need the platform flag workaround.

Verifying the FixOnce your container is up and running, you can double-check that it is using the correct architecture. Run this command to inspect the metadata:

docker inspect <container_id> | grep Architecture

Even on an ARM-based Mac, the output should read "Architecture": "amd64". You might see a yellow warning icon in the Docker Desktop dashboard stating the image platform does not match the host. You can safely ignore this; it is just a reminder that the container is running under emulation.