How to fix Error response from daemon: no matching manifest for linux/arm64 in the manifest list entries in Docker

DockerINTERMEDIATEMEDIUM

This error occurs when pulling a Docker image that doesn't have a variant for your ARM64 architecture (Apple Silicon, Raspberry Pi, AWS Graviton). The fix involves using the --platform flag to emulate amd64, finding ARM-compatible images, or building multi-architecture images with Docker Buildx.

What this error means

This error indicates that the Docker image you're trying to pull doesn't have a version compiled for the ARM64 CPU architecture. Docker images are built for specific processor architectures, and when Docker requests an image from a registry like Docker Hub, it looks for a manifest that matches your system's architecture. On ARM64 systems (Apple Silicon Macs, Raspberry Pi 4, AWS Graviton, and other ARM-based devices), Docker looks for images tagged with `linux/arm64` or `linux/arm64/v8`. When the image maintainer only provides builds for Intel/AMD processors (`linux/amd64`), Docker cannot find a matching manifest entry and throws this error. This is particularly common with older images, specialized tools, or software that hasn't been ported to ARM yet. The issue became more prevalent with the release of Apple Silicon Macs (M1/M2/M3/M4 chips) and the growing adoption of ARM-based servers for their power efficiency.

How to fix "Error response from daemon: no matching manifest for linux/arm64 in the manifest list entries"

1Use the --platform flag to run with emulation

The quickest fix is to run the amd64 version of the image using emulation:

bash

# Pull the amd64 version explicitly
docker pull --platform linux/amd64 mysql:5.7

# Run with platform specification
docker run --platform linux/amd64 mysql:5.7

# Works for any image without ARM support
docker run --platform linux/amd64 <image-name>:<tag>

Docker Desktop on macOS and Windows includes QEMU emulation by default, allowing amd64 containers to run on ARM hosts. On Linux, you may need to install QEMU (see step 5).

Note: Emulated containers run 2-5x slower than native ones. This is acceptable for development but not recommended for production.

2Set platform in Docker Compose

For Docker Compose projects, add the platform directive to services that lack ARM support:

yaml

# docker-compose.yml
version: '3.8'
services:
  mysql:
    image: mysql:5.7
    platform: linux/amd64  # Force amd64 with emulation
    ports:
      - "3306:3306"
    environment:
      MYSQL_ROOT_PASSWORD: secret

  redis:
    image: redis:alpine  # Has native ARM64 support - no platform needed
    ports:
      - "6379:6379"

Only add platform: linux/amd64 to services that don't have ARM support. Most popular images like Redis, PostgreSQL, and Nginx now have native ARM64 builds.

3Set a default platform environment variable

If you frequently work with amd64-only images, set a default platform:

bash

# Set for current terminal session
export DOCKER_DEFAULT_PLATFORM=linux/amd64

# Add to shell profile for persistence
# 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

This forces all Docker commands to request amd64 images. Remove or unset this variable when you want to use native ARM images:

bash

unset DOCKER_DEFAULT_PLATFORM

Warning: Using this globally may cause you to accidentally run emulated containers when native ones are available, impacting performance.

4Find an ARM64-compatible alternative image

Before using emulation, check if a native ARM64 version exists:

bash

# Inspect available platforms for an image
docker buildx imagetools inspect mysql:latest

# Example output showing multi-arch support:
# Name:      docker.io/library/mysql:latest
# Platforms: linux/amd64, linux/arm64/v8

Common strategies for finding ARM-compatible images:

1. Use newer versions - ARM support often comes in recent releases

bash

# mysql:5.7 has no ARM support, but mysql:8.0+ does
   docker pull mysql:8.0

2. Try official ARM images - Some images have explicit ARM variants

bash

docker pull arm64v8/mysql
   docker pull arm64v8/nginx

3. Use alternative images with the same functionality

bash

# MariaDB as MySQL alternative (has ARM64 support)
   docker pull mariadb:latest

4. Check image documentation on Docker Hub for platform support

5Enable QEMU emulation on Linux

Docker Desktop (macOS/Windows) includes QEMU by default, but Linux requires manual setup:

bash

# Option 1: Install QEMU packages (Ubuntu/Debian)
sudo apt-get update
sudo apt-get install -y qemu-user-static binfmt-support

# Option 2: Use Docker's QEMU image (works on any Linux)
docker run --privileged --rm tonistiigi/binfmt --install all

# Verify QEMU is registered
ls /proc/sys/fs/binfmt_misc/qemu-*

# Test amd64 emulation
docker run --platform linux/amd64 alpine uname -m
# Should output: x86_64

After setting up QEMU, the --platform linux/amd64 flag will work to run x86 images on ARM hosts.

6Enable Rosetta for faster emulation (macOS only)

On Apple Silicon Macs, Rosetta 2 provides faster x86 emulation than QEMU:

1. Open Docker Desktop
2. Click the gear icon (Settings)
3. Go to General
4. Enable "Use Rosetta for x86_64/amd64 emulation on Apple Silicon"
5. Click Apply & restart

bash

# After restart, verify Rosetta is being used
docker run --platform linux/amd64 alpine uname -m
# Should output: x86_64

Rosetta provides significantly better performance than QEMU for x86 emulation on Apple Silicon, making development with amd64-only images much more practical.

Note: Requires macOS 13 (Ventura) or later.

7Build your own multi-architecture image

If you maintain the image or need a custom build, create a multi-platform image with Buildx:

bash

# Create and use a builder that supports multi-platform
docker buildx create --name multiarch-builder --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
docker buildx imagetools inspect your-registry/your-image:latest

The resulting image will automatically serve the correct architecture when pulled on different machines. This is the best solution for production environments with mixed architectures.

Advanced notes

### Why Some Images Don't Have ARM64 Support

Several factors contribute to missing ARM64 support:

1. Legacy software - Older applications may have assembly code or dependencies that are x86-specific
2. Compilation complexity - Some software requires significant porting effort for ARM
3. Testing resources - Maintainers may not have ARM hardware for testing
4. Low demand historically - ARM servers and development machines were rare until recently

### Performance Impact of Emulation

Running containers under emulation has measurable overhead:

| Workload Type | Emulation Overhead |
|--------------|-------------------|
| I/O-bound (web servers, databases) | 1.5-2x slower |
| CPU-bound (compilation, encoding) | 3-5x slower |
| Heavy computation | 5-10x slower |

For production workloads, always prefer native images.

### Checking Platform Support Before Pulling

Create a shell function to check image platforms:

bash

# Add to ~/.zshrc or ~/.bashrc
check_platforms() {
  docker buildx imagetools inspect "$1" 2>/dev/null | grep -A 20 "Manifests:" || echo "Image not found or no manifest list"
}

# Usage
check_platforms nginx:latest
check_platforms mysql:5.7

### CI/CD Considerations

When building for multiple architectures in CI/CD:

yaml

# GitHub Actions example
name: Build Multi-Arch
on: [push]

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: 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 in Dockerfiles

When building multi-arch images with platform-specific binaries:

dockerfile

FROM alpine:latest

# Use build argument to detect architecture
ARG TARGETARCH

# Download architecture-specific binary
RUN wget https://example.com/tool-${TARGETARCH}.tar.gz && \
    tar xzf tool-${TARGETARCH}.tar.gz

# TARGETARCH will be 'amd64' or 'arm64' based on build platform

### MySQL-Specific Workaround

MySQL 5.7 is a common culprit (no ARM support). Options:

yaml

# Option 1: Use MySQL 8 (has ARM64 support)
services:
  db:
    image: mysql:8.0

# Option 2: Use MariaDB (drop-in replacement, ARM support)
services:
  db:
    image: mariadb:10.11

# Option 3: Emulate MySQL 5.7 if required
services:
  db:
    image: mysql:5.7
    platform: linux/amd64

How to fix Error response from daemon: no matching manifest for linux/arm64 in the manifest list entries in Docker

What this error means

Typical symptoms

Common causes

How to fix "Error response from daemon: no matching manifest for linux/arm64 in the manifest list entries"

Advanced notes

Related errors

Official resources & further reading