This error occurs when pulling a Docker image that doesn't have a version compiled for your CPU architecture. Common on Apple Silicon Macs (M1/M2/M3) and ARM-based systems like Raspberry Pi when trying to use x86/amd64-only images. Fix by using the --platform flag, setting DOCKER_DEFAULT_PLATFORM, or finding multi-architecture images.
This error means Docker cannot find an image variant that matches your system's CPU architecture in the image's manifest list. Docker images are compiled for specific CPU architectures (like amd64/x86_64 or arm64/aarch64), and the manifest list acts as an index pointing to architecture-specific versions. When you pull an image, Docker checks the manifest list for a variant matching your host platform. If the image only contains linux/amd64 entries but you're on a linux/arm64 system (like Apple Silicon Mac or Raspberry Pi), Docker cannot proceed because there's no compatible binary to run. This became a widespread issue with the adoption of Apple Silicon Macs (M1/M2/M3/M4 chips) and ARM-based cloud instances. Many older images were built only for x86/amd64, and while Docker can emulate different architectures, it cannot pull an image if the manifest explicitly lacks your platform.
Before applying fixes, verify which platforms the image actually supports:
# Using Docker buildx imagetools (recommended)
docker buildx imagetools inspect nginx:latest
# Using docker manifest (older method)
docker manifest inspect nginx:latest
# Example output showing supported platforms:
# Name: docker.io/library/nginx:latest
# MediaType: application/vnd.oci.image.index.v1+json
# Digest: sha256:...
#
# Platforms:
# linux/amd64
# linux/arm/v5
# linux/arm/v7
# linux/arm64 <-- ARM64 support present
# linux/386If your platform (linux/arm64 or linux/amd64) is not listed, the image genuinely doesn't support it, and you'll need to use emulation or find an alternative image.
If the image doesn't support your architecture natively, force Docker to use emulation:
# Pull an amd64 image on ARM host (Apple Silicon, Raspberry Pi)
docker pull --platform linux/amd64 mysql:5.7
# Run with explicit platform specification
docker run --platform linux/amd64 mysql:5.7
# For any platform mismatch, specify the available platform
docker run --platform linux/amd64 your-image:tagImportant: This requires QEMU emulation, which is built into Docker Desktop on macOS but may need manual setup on Linux. Emulated containers run 2-5x slower than native ones.
Avoid typing --platform on every command by setting a default:
# Set for current terminal session
export DOCKER_DEFAULT_PLATFORM=linux/amd64
# Make it permanent by adding to shell profile
# For zsh (default on macOS):
echo 'export DOCKER_DEFAULT_PLATFORM=linux/amd64' >> ~/.zshrc
source ~/.zshrc
# For bash:
echo 'export DOCKER_DEFAULT_PLATFORM=linux/amd64' >> ~/.bashrc
source ~/.bashrc
# Verify it's set
echo $DOCKER_DEFAULT_PLATFORMNow all docker pull and run commands will attempt amd64 images with emulation when native ARM64 isn't available.
For Docker Compose projects, add the platform key to services that need it:
# docker-compose.yml
version: '3.8'
services:
database:
image: mysql:5.7
platform: linux/amd64 # Force amd64 with emulation on ARM hosts
environment:
MYSQL_ROOT_PASSWORD: secret
ports:
- "3306:3306"
app:
image: your-app:latest
# No platform specified - uses native architecture
depends_on:
- databaseThis ensures the MySQL 5.7 image (which may lack ARM64 support) runs under emulation while your application uses native architecture.
Instead of emulation, look for images that natively support your platform:
# Check Docker Hub for official multi-arch images
# Many official images now support: linux/amd64, linux/arm64, linux/arm/v7
# Examples of well-maintained multi-arch images:
docker pull nginx:latest # Supports amd64 + arm64
docker pull postgres:15 # Supports amd64 + arm64
docker pull redis:7 # Supports amd64 + arm64
docker pull node:20 # Supports amd64 + arm64
# For MySQL, use version 8+ for ARM64 support
docker pull mysql:8.0 # Has ARM64 support
# Instead of mysql:5.7 which is amd64-only
# MariaDB as MySQL alternative with ARM64 support
docker pull mariadb:11When possible, upgrade to newer versions or switch to alternatives that provide native ARM64 support for better performance.
Docker Desktop includes QEMU automatically, but Linux servers need manual setup:
# Option 1: Install via package manager (Ubuntu/Debian)
sudo apt-get update
sudo apt-get install -y qemu-user-static binfmt-support
# Option 2: Use Docker's multiarch image (works on any Linux)
docker run --privileged --rm tonistiigi/binfmt --install all
# Verify QEMU is registered
ls /proc/sys/fs/binfmt_misc/qemu-*
# Should show: qemu-aarch64, qemu-arm, qemu-x86_64, etc.
# Test cross-architecture execution
docker run --platform linux/arm64 arm64v8/alpine uname -m
# Should output: aarch64 (even on x86 host)This enables pulling and running images for any supported architecture, though with performance overhead.
If you control the Dockerfile, build a multi-architecture image:
# Create a builder with multi-platform support
docker buildx create --name mybuilder --use --bootstrap
# Build for multiple architectures and push to registry
docker buildx build \
--platform linux/amd64,linux/arm64 \
--tag your-registry/your-image:latest \
--push \
.
# Verify the multi-arch manifest was created
docker buildx imagetools inspect your-registry/your-image:latestThe registry stores separate image layers for each architecture, and Docker automatically pulls the correct one based on host platform.
### Understanding Docker Manifests
Docker images use a manifest system to support multiple architectures:
- Single-platform image: One manifest pointing to one set of layers for one architecture
- Multi-platform image: A manifest list (or OCI image index) containing multiple manifests, one per supported architecture
When you pull nginx:latest, Docker:
1. Fetches the manifest list from the registry
2. Finds the entry matching your host platform (e.g., linux/arm64)
3. Pulls the layers referenced by that platform's manifest
The "no matching manifest" error occurs at step 2 when no entry matches your platform.
### Performance Impact of Emulation
Running amd64 containers on ARM hosts (or vice versa) through QEMU emulation has significant overhead:
| Workload Type | Slowdown Factor |
|---------------|-----------------|
| Simple I/O (web servers, proxies) | 1.5-2x slower |
| Database operations | 2-3x slower |
| CPU-intensive (compilation, encoding) | 3-5x slower |
| Floating-point heavy (ML, scientific) | 5-10x slower |
For development and testing, this is usually acceptable. For production workloads, always use native architecture images.
### Docker Desktop Rosetta Acceleration (macOS)
On Apple Silicon Macs, Docker Desktop can use Rosetta 2 instead of QEMU for faster x86 emulation:
1. Open Docker Desktop > Settings > General
2. Enable "Use Rosetta for x86_64/amd64 emulation on Apple Silicon"
3. Restart Docker Desktop
Rosetta provides significantly better performance for amd64 containers compared to QEMU emulation.
### CI/CD Multi-Architecture Builds
For GitHub Actions, use the official Docker actions:
name: Multi-Arch Build
on:
push:
branches: [main]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Set up QEMU
uses: docker/setup-qemu-action@v3
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v3
- name: Login to Docker Hub
uses: docker/login-action@v3
with:
username: ${{ secrets.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_TOKEN }}
- name: Build and push
uses: docker/build-push-action@v5
with:
platforms: linux/amd64,linux/arm64
push: true
tags: username/app:latest### Common Images Without ARM64 Support
Some popular images historically lacked ARM64 variants:
- MySQL 5.x (use MySQL 8.x or MariaDB instead)
- Older Elasticsearch versions (use 7.x+ or OpenSearch)
- Some CI tool images (Jenkins LTS has ARM64 now)
- Unmaintained community images
Always check the image's Docker Hub page or run docker buildx imagetools inspect to verify platform support before deployment.
image operating system "linux" cannot be used on this platform
How to fix 'image operating system linux cannot be used on this platform' in Docker
manifest unknown: manifest unknown
How to fix 'manifest unknown' in Docker
cannot open '/etc/passwd': Permission denied
How to fix 'cannot open: Permission denied' in Docker
Error response from daemon: failed to create the ipvlan port
How to fix 'failed to create the ipvlan port' in Docker
toomanyrequests: Rate exceeded for anonymous users
How to fix 'Rate exceeded for anonymous users' in Docker Hub