Docker on ARM: Apple Silicon and Raspberry Pi
Explore running Docker on ARM64 hardware like Apple Silicon (M1/M2/M3/M4) and Raspberry Pi, comparing native ARM execution against Rosetta 2 and QEMU emulation.
Published on • November 17, 2026
AI Assistant
The widespread adoption of ARM64 architecture—from Apple Silicon Macs (M1 through M4 series) to single-board computers like the Raspberry Pi 4/5 and cloud instances (AWS Graviton, Ampere Altra)—has fundamentally transformed containerized software development.
While running x86_64 (amd64) images on ARM hosts is technically possible via emulation, running native ARM64 images yields dramatic performance, energy efficiency, and resource utilization improvements.
Architecture Alignment: ARM64 vs AMD64
Containers share the host operating system kernel. When a container running on an ARM64 host executes instructions compiled for x86_64 (linux/amd64), CPU instructions must be translated dynamically.
+-------------------------------------------------------------------+
| Container Architecture | Host Architecture | Execution Mode |
+------------------------+-------------------+----------------------+
| linux/arm64 | ARM64 (M1/Pi) | Native (Fastest) |
| linux/amd64 | ARM64 (M1 Mac) | Rosetta 2 Emulation |
| linux/amd64 | ARM64 (Linux/Pi) | QEMU Emulation (Slow)|
+-------------------------------------------------------------------+
1. Native ARM64 Execution
When your image matches the host CPU (linux/arm64), instructions execute directly on hardware with zero emulation overhead.
2. Apple Silicon: Rosetta 2 Emulation vs QEMU
On macOS, Docker Desktop supports Rosetta 2 for Linux (via Apple Virtualization Framework). Rosetta 2 translates x86_64 binary instructions to ARM64 ahead-of-time/just-in-time, delivering significantly faster execution than traditional software-emulated QEMU.
To verify or enable Rosetta 2 in Docker Desktop for Mac:
- Open Docker Desktop Settings -> General or Virtualization engine.
- Ensure Use Rosetta for x86/amd64 emulation on Apple Silicon is checked.
3. Linux / Raspberry Pi: QEMU Emulation
On Linux ARM64 hosts (like Raspberry Pi OS 64-bit or Ubuntu ARM), running linux/amd64 images relies on qemu-user-static. While functional for basic utilities, heavy workloads (such as database indexing or compilation) run 3x to 10x slower under QEMU emulation.
Identifying Container Architecture
You can inspect the CPU architecture of any running container or image using docker inspect or uname:
# Check architecture of a running container
docker exec my-container uname -m
- Returns
aarch64orarm64: Container is running natively on ARM64. - Returns
x86_64: Container is running under emulation.
To inspect an image manifest directly from a registry:
docker buildx imagetools inspect python:3.12-alpine
Output highlights multi-architecture availability:
Platform: linux/amd64
Platform: linux/arm64
Platform: linux/arm/v7
Running Architecture-Specific Containers
Docker CLI allows forcing a specific platform target using the --platform flag:
# Force running an x86_64 image under Rosetta 2/QEMU on an ARM host
docker run --platform linux/amd64 -d postgres:16
# Force running native ARM64 image
docker run --platform linux/arm64 -d postgres:16
In docker-compose.yml:
version: '3.8'
services:
database:
image: postgres:16
platform: linux/arm64
ports:
- "5432:5432"
Developing Multi-Arch Dockerfiles
To write Dockerfiles that build cleanly on both Apple Silicon, Raspberry Pi, and x86_64 CI runners, leverage BuildKit automatic platform arguments:
# syntax=docker/dockerfile:1
FROM --platform=$BUILDPLATFORM node:22-alpine AS build
ARG TARGETPLATFORM
ARG BUILDPLATFORM
RUN echo "Building on $BUILDPLATFORM, targeting $TARGETPLATFORM"
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
FROM node:22-alpine
WORKDIR /app
COPY --from=build /app/dist ./dist
CMD ["node", "dist/server.js"]
Troubleshooting Common ARM Migration Errors
Error: exec format error (exec /bin/sh: exec format error)
This error occurs when attempting to run a container compiled for a different CPU architecture on a Linux host that lacks binary emulation support (such as a bare Raspberry Pi without qemu-user-static installed).
Fix: Ensure your Dockerfile pulls an ARM64 base image or register QEMU emulators on your Linux host:
# Install QEMU multi-arch emulation handlers on Linux
docker run --privileged --rm tonistiigi/binfmt --install all
Takeaway: Running native ARM64 container images on Apple Silicon and Raspberry Pi eliminates emulation bottlenecks and delivers peak performance. Enable Rosetta 2 on macOS for legacy x86 images, use --platform linux/arm64 when pulling, and build multi-arch images with BuildKit.