How to fix WARNING: The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8) in Docker

DockerINTERMEDIATEMEDIUMUpdated Dec 6, 2025· 314 views

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.

Quick fix

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

# 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}}'
  1. Run with explicit platform flag
  2. Set default platform via environment variable
  3. Specify platform in Docker Compose
  4. Enable Rosetta emulation on macOS (Apple Silicon)
docker — error
# 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}}'
WARNING: The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8)

What this error means

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.

Typical symptoms

  • Warning message: 'The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8)'
  • Containers start but run significantly slower than expected
  • Random crashes or 'exec format error' when containers try to execute binaries
  • CI/CD pipelines fail when moving between different architecture runners
  • Docker images work on Intel Macs but fail on Apple Silicon Macs
  • Images pulled from Docker Hub don't work on Raspberry Pi or ARM servers
  • Performance degradation in containerized applications on new ARM-based hardware

Common causes

  1. Pulling an amd64-only image on an ARM64 host like Apple Silicon Mac or Raspberry Pi (most common)
  2. The image maintainer hasn't published multi-architecture variants
  3. Docker Compose or Kubernetes manifests don't specify the correct platform
  4. Base image in Dockerfile doesn't support the target architecture
  5. CI/CD builds produce single-architecture images that don't match deployment environment
  6. Legacy images from before ARM architecture became popular
  7. Using older Docker versions that don't handle multi-arch properly
  8. Buildx not configured correctly for cross-platform builds

How to fix "WARNING: The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8)"

1Run with explicit platform flag

Force Docker to use emulation for a specific architecture with the --platform flag:

bash
# 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.

2Set default platform via environment variable

Avoid passing --platform on every command by setting a default:

bash
# 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 platform

Now 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.

3Specify platform in Docker Compose

For Docker Compose projects, add the platform key to services:

yaml
# 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: secret

This ensures consistent behavior across development machines with different architectures.

4Enable Rosetta emulation on macOS (Apple Silicon)

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

bash
# Verify Rosetta is being used (after restart)
docker run --platform linux/amd64 alpine uname -m
# Should output: x86_64

Rosetta provides significantly better performance than QEMU for running amd64 containers on ARM Macs. This is the recommended approach for development on Apple Silicon.

5Build multi-platform images with Buildx

The best long-term solution is building images that support multiple architectures:

bash
# 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:latest

The registry stores a manifest list pointing to architecture-specific images. When pulled, Docker automatically selects the right variant for the host.

6Install QEMU for cross-platform builds on Linux

On Linux servers (not Docker Desktop), you may need to set up QEMU manually:

bash
# 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: aarch64

This is required for building ARM images in CI/CD pipelines running on x86 infrastructure.

7Find or request multi-architecture images

Before applying workarounds, check if a native image exists:

bash
# 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.

Advanced notes

### 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:

yaml
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:

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:

bash
# 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 multiarch

This 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:

yaml
# 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:latest

Or let Kubernetes automatically select based on multi-arch images:

yaml
# No selector needed if image supports multiple platforms
spec:
  containers:
    - name: app
      image: myapp:multiarch  # Has both amd64 and arm64

Frequently asked questions

What does "WARNING: The requested image's platform (linux/amd64) does not match t" mean?
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.
How do I fix "WARNING: The requested image's platform (linux/amd64) does not match t"?
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.
What causes "WARNING: The requested image's platform (linux/amd64) does not match t"?
Pulling an amd64-only image on an ARM64 host like Apple Silicon Mac or Raspberry Pi (most common) The image maintainer hasn't published multi-architecture variants Docker Compose or Kubernetes manifests don't specify the correct platform
Is the "WARNING: The requested image's platform (linux/amd64) does not match t" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading