Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

Docker warns that the image platform linux/amd64 does not match the arm64 host

ErrorThe requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8)

Short answer

The image was built for linux/amd64 and your machine is arm64, such as an Apple Silicon Mac. Docker Desktop still runs it through emulation, which is slower. Choose an image variant that has arm64, set the platform on purpose with --platform, or build your own image for both platforms.

  • Applies to Docker Desktop 4.x on macOS (Apple Silicon), Docker Engine
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    List the platforms the image is published for. If linux/arm64 is there, you can run natively. If only linux/amd64 is there, you must emulate or choose another image.

    docker buildx imagetools inspect IMAGE:TAG
  2. 2Match what you see, then jump to its fix

    1. 1imagetools inspect lists linux/amd64 and no arm64 entryThe image is published for amd64 onlyFix
    2. 2imagetools inspect lists linux/arm64/v8, yet your compose file or FROM line forces amd64An arm64 variant exists, but amd64 is pinned or already pulledFix
    3. 3The image is yours and was built on one CPU type, then run on anotherYour own image was built for one platform onlyFix

What does the error look like?

  • The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8)

Cause 1 of 3

The image is published for amd64 only

1Check

A manifest list holds one entry per platform. Without an arm64 entry, an arm64 host has nothing native to pull.

docker buildx imagetools inspect IMAGE:TAG

2Fix

Run it under emulation by naming the platform, or look for a different tag or image that publishes arm64. Expect slower speed under emulation.

docker run --platform linux/amd64 IMAGE:TAG

# docker-compose.yml
services:
  app:
    image: IMAGE:TAG
    platform: linux/amd64

3Verify

The warning no longer says no platform was requested, and the container starts.

docker compose up -d && docker compose ps

Confirmed by docs.docker.com

Did this fix it?

Cause 2 of 3

An arm64 variant exists, but amd64 is pinned or already pulled

1Check

Search for a platform key in compose files and for --platform in Dockerfile FROM lines.

grep -R -n -E 'platform' docker-compose*.yml Dockerfile

2Fix

Remove the amd64 pin, or set platform to linux/arm64/v8, then pull again.

docker compose pull
docker compose up -d

3Verify

The container starts without the mismatch warning.

docker compose ps

Confirmed by docs.docker.com

Did this fix it?

Cause 3 of 3

Your own image was built for one platform only

1Check

A plain build produces the platform of the build machine. List the platforms of the image you pushed.

docker buildx imagetools inspect my-image

2Fix

Build and push a multi-platform image.

docker buildx build --platform linux/amd64,linux/arm64 -t my-image .

3Verify

Inspect the pushed tag and look for both platforms.

docker buildx imagetools inspect my-image

Confirmed by docs.docker.com

Did this fix it?

How do I stop it coming back?

  • Build and publish multi-platform images for any image your team pulls on both Mac and Linux servers.
  • Write the platform in compose files when you rely on emulation, so the choice is visible.
  • Treat emulation as a development convenience, because it can be much slower.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Servers

A dev container port does not open in the browser when Docker runs on a remote host

If your application only accepts calls from localhost, it will reject connections from published ports

Three things usually break it: the app listens only on localhost inside the container, so published ports are rejected; you open the container port instead of the mapped localhost port VS Code shows; or you changed appPort or a Compose ports list and did not rebuild.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.