Running amd64 Docker Images on arm64 Hosts

Problem

When attempting to run an amd64/x86-64 Docker image on an arm64 host system (such as Apple M1/M2 Macs), you may encounter platform compatibility issues. The Docker daemon detects the architecture mismatch and warns that the requested image's platform (linux/amd64) doesn't match the host platform (linux/arm64/v8).

If the container exits immediately after starting despite using the --platform flag, you need additional configuration to successfully run cross-platform containers.

Solution

Use the Platform Flag Correctly

The primary solution is to use Docker's --platform flag to specify the target architecture. However, the placement of this flag is crucial for it to work properly:

docker run --platform linux/amd64 your-image-name

WARNING

Ensure --platform linux/amd64 is placed immediately after the run command. Placing it elsewhere in the command may cause it to be ignored.

Handle Immediate Container Exit

If your container exits immediately after starting, this is likely due to the container's entrypoint or command failing on the emulated architecture. You can override the entrypoint to debug or use a compatible shell:

docker run -it --platform linux/amd64 --entrypoint=/bin/bash your-image-name

The -it flags keep the container interactive, and overriding the entrypoint to /bin/bash provides a shell session for troubleshooting.

Verify Platform Emulation

To confirm that platform emulation is working correctly, test with a base Ubuntu image:

# Test ARM64 architecture
docker run --rm -ti --platform linux/arm64 ubuntu:latest uname -m

# Test AMD64 architecture
docker run --rm -ti --platform linux/amd64 ubuntu:latest uname -m

The first command should return aarch64 and the second should return x86_64, demonstrating successful architecture emulation.

How It Works

Docker on Apple Silicon Macs uses Rosetta 2 translation technology to enable running x86-64 containers on arm64 hardware. This transparent emulation allows most amd64 images to run without modification, though performance may be slightly reduced compared to native arm64 images.

INFO

Not all Docker images are available for ARM64 architecture. The --platform linux/amd64 flag forces Docker to use Intel-based images under emulation when ARM64 versions aren't available.

Troubleshooting

If you continue to experience issues:

1. Update Docker Desktop: Ensure you're running the latest version of Docker Desktop for Mac, which includes the most recent Rosetta 2 integration improvements.

2. Check image compatibility: Some images may have architecture-specific dependencies that don't work well under emulation.

3. Enable Rosetta explicitly: In Docker Desktop settings, ensure "Use Rosetta for x86/amd64 emulation on Apple Silicon" is enabled.

4. Resource considerations: Emulated containers may require more memory and CPU resources than native ones.

Alternative Approaches

For production environments or frequent use, consider these alternatives:

• Multi-architecture images: Use docker buildx to create multi-arch images that work on both amd64 and arm64
• Native ARM64 images: Whenever possible, use images built specifically for ARM64 architecture
• Remote AMD64 host: For complex scenarios, consider running AMD64 containers on a remote x86-64 host

TIP

For long-term solutions, encourage image maintainers to provide multi-architecture builds using Docker Buildx, which creates manifests that automatically serve the correct architecture for the host platform.