Skip to content
Blog

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:

  1. Open Docker Desktop Settings -> General or Virtualization engine.
  2. 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 aarch64 or arm64: 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.

Sources