This error occurs when trying to run a Docker image built for a different CPU architecture than your host machine. Common scenarios include running x86/amd64 images on Apple Silicon Macs (ARM64) or Raspberry Pi devices. The fix involves using the --platform flag, building multi-architecture images, or enabling emulation.
This warning indicates an architecture mismatch between the Docker image and your host system's CPU. Docker images are compiled for specific CPU architectures (like x86_64/amd64 or ARM64/aarch64), and the code inside must match the processor's instruction set. The most common scenario is running images built for Intel/AMD processors (linux/amd64) on Apple Silicon Macs (M1/M2/M3/M4 chips) or ARM-based devices like Raspberry Pi, which use the linux/arm64 architecture. The reverse also occurs: trying to run ARM images on x86 machines. While Docker can emulate different architectures using QEMU, this comes with significant performance overhead (2-5x slower for CPU-intensive tasks). Containers may also experience compatibility issues or crashes when running under emulation. For production workloads, it's best to use native images matching your architecture or build multi-platform images that support multiple architectures.
Force Docker to use emulation for a specific architecture with the --platform flag:
# Run an amd64 image on ARM host using emulation
docker run --platform linux/amd64 your-image:tag
# Run an ARM image on x86 host
docker run --platform linux/arm64 your-image:tag
# Check what platform an image was built for
docker image inspect your-image:tag --format '{{.Os}}/{{.Architecture}}'This works if QEMU emulation is available (default on Docker Desktop). Note that emulated containers run 2-5x slower than native ones, so this is best for development or testing, not production.
Avoid passing --platform on every command by setting a default:
# Set for current session
export DOCKER_DEFAULT_PLATFORM=linux/amd64
# Add to shell profile for persistence (~/.bashrc, ~/.zshrc)
echo 'export DOCKER_DEFAULT_PLATFORM=linux/amd64' >> ~/.zshrc
source ~/.zshrc
# Verify the setting
docker info | grep -i platformNow all docker run and docker pull commands will default to the specified platform. Remove or unset the variable when you want native architecture behavior again.
For Docker Compose projects, add the platform key to services:
# docker-compose.yml
version: '3.8'
services:
web:
image: nginx:latest
platform: linux/amd64 # Force amd64 even on ARM hosts
ports:
- "8080:80"
database:
image: postgres:15
platform: linux/arm64 # Use native ARM if available
environment:
POSTGRES_PASSWORD: secretThis ensures consistent behavior across development machines with different architectures.
Docker Desktop on Apple Silicon can use Rosetta 2 for faster x86 emulation:
1. Open Docker Desktop
2. Go to Settings (gear icon)
3. Select General
4. Enable "Use Rosetta for x86_64/amd64 emulation on Apple Silicon"
5. Click Apply & restart
# Verify Rosetta is being used (after restart)
docker run --platform linux/amd64 alpine uname -m
# Should output: x86_64Rosetta provides significantly better performance than QEMU for running amd64 containers on ARM Macs. This is the recommended approach for development on Apple Silicon.
The best long-term solution is building images that support multiple architectures:
# Create a new builder instance (required for multi-platform)
docker buildx create --name multiarch-builder --use --bootstrap
# Build and push multi-architecture image
docker buildx build \
--platform linux/amd64,linux/arm64 \
--tag your-registry/your-image:latest \
--push \
.
# Verify the platforms in the manifest
docker buildx imagetools inspect your-registry/your-image:latestThe registry stores a manifest list pointing to architecture-specific images. When pulled, Docker automatically selects the right variant for the host.
On Linux servers (not Docker Desktop), you may need to set up QEMU manually:
# Install QEMU and register binary formats (Ubuntu/Debian)
sudo apt-get update
sudo apt-get install -y qemu-user-static binfmt-support
# Alternative: Use Docker's QEMU image (works on any Linux)
docker run --privileged --rm tonistiigi/binfmt --install all
# Verify registration
ls /proc/sys/fs/binfmt_misc/qemu-*
# Test ARM emulation on x86 host
docker run --platform linux/arm64 arm64v8/alpine uname -m
# Should output: aarch64This is required for building ARM images in CI/CD pipelines running on x86 infrastructure.
Before applying workarounds, check if a native image exists:
# Check available platforms for an image on Docker Hub
docker buildx imagetools inspect nginx:latest
# Example output shows supported platforms:
# Name: nginx:latest
# Platforms: linux/amd64, linux/arm/v7, linux/arm64, ...If an image doesn't support your architecture:
- Check for alternative images (e.g., arm64v8/nginx instead of nginx)
- Look for community-maintained multi-arch forks
- Open a GitHub issue requesting ARM64 support
- Fork the Dockerfile and build your own multi-arch version
Many popular images now support both amd64 and arm64 - the issue is often with older or less maintained images.
### Performance Comparison: Native vs Emulated
Running containers under emulation has significant performance implications:
| Workload Type | Performance Impact |
|---------------|-------------------|
| I/O bound (web servers, databases) | ~1.5-2x slower |
| CPU bound (compilation, processing) | ~3-5x slower |
| Heavy floating-point operations | ~5-10x slower |
For development and testing, emulation is usually acceptable. For production, always use native images.
### Building Multi-Platform Images in CI/CD
Example GitHub Actions workflow for multi-architecture builds:
name: Build Multi-Arch Image
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: user/app:latest### Handling Architecture-Specific Dependencies
Some software has different packages for different architectures. Handle this in your Dockerfile:
FROM alpine:latest
# Detect architecture and install appropriate package
RUN ARCH=$(uname -m) && \
if [ "$ARCH" = "x86_64" ]; then \
ARCH="amd64"; \
elif [ "$ARCH" = "aarch64" ]; then \
ARCH="arm64"; \
fi && \
wget https://example.com/package-${ARCH}.tar.gz### Using Native Builders for Better Performance
Instead of emulating everything on one machine, use multiple native builders:
# Create builder with multiple native nodes
docker buildx create --name multiarch \
--node amd64-node --platform linux/amd64
docker buildx create --name multiarch --append \
--node arm64-node --platform linux/arm64
docker buildx use multiarchThis requires SSH access to machines of each architecture but provides native build performance.
### Kubernetes and Multi-Architecture
When deploying to Kubernetes clusters with mixed architectures:
# Use node selectors to ensure correct placement
apiVersion: apps/v1
kind: Deployment
spec:
template:
spec:
nodeSelector:
kubernetes.io/arch: arm64
containers:
- name: app
image: myapp:latestOr let Kubernetes automatically select based on multi-arch images:
# No selector needed if image supports multiple platforms
spec:
containers:
- name: app
image: myapp:multiarch # Has both amd64 and arm64image 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