Docker warns that the image platform linux/amd64 does not match the arm64 host
The 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.
Fix it fast
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:TAG2Match what you see, then jump to its fix
- 1
imagetools inspect lists linux/amd64 and no arm64 entryThe image is published for amd64 onlyFix - 2
imagetools 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
The image is yours and was built on one CPU type, then run on anotherYour own image was built for one platform onlyFix
- 1
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:TAG2Fix
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/amd643Verify
The warning no longer says no platform was requested, and the container starts.
docker compose up -d && docker compose psConfirmed by docs.docker.com
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 Dockerfile2Fix
Remove the amd64 pin, or set platform to linux/arm64/v8, then pull again.
docker compose pull
docker compose up -d3Verify
The container starts without the mismatch warning.
docker compose psConfirmed by docs.docker.com
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-image2Fix
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-imageConfirmed by docs.docker.com
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
Apache logs SIGWINCH and exits on its own
the httpd container stops although nothing crashed
SIGWINCH is Apache's graceful-stop signal.
2 causes, each with a fixServers
sam local fails: Running AWS SAM projects locally requires Docker
Cannot connect to the Docker daemon. Is the docker daemon running on this host?
sam local start-api and sam local invoke run your function inside a Docker container, so SAM stops if it cannot talk to Docker.
3 causes, each with a fixServers
dnf fails to download repo metadata in a CentOS 8 Docker build
The same Dockerfile built fine before 2022
CentOS Linux 8 reached end of life on 31 December 2021 and its content left the mirrors.
2 causes, each with a fixServers
pip install confluent-kafka fails because librdkafka/rdkafka.h is missing
pip stops while building confluent-kafka from source
The error means pip is compiling confluent-kafka from source, and the compiler cannot find the librdkafka C headers.
3 causes, each with a fixServers
Cypress says the npm package is installed but the binary is missing
Cypress binary is missing after npm install in CI or in a Docker build
The npm package is only a launcher.
3 causes, each with a fixServers
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