← Back to DevBytes
Docker July 07, 2026 14 min read

Docker ARM vs AMD64 Images: Production Guide

Understanding Docker Multi-Architecture Images

When you pull a Docker image from a registry, you're not just downloading a single binary blob. Behind the scenes, Docker uses a sophisticated manifest system that allows a single image tag to point to multiple architecture-specific variants. This is what makes docker pull nginx:latest work seamlessly whether you're on an Intel MacBook, an AWS Graviton instance, or a Raspberry Pi.

An AMD64 (x86_64) image contains binaries compiled for Intel and AMD processors — the traditional server chips that have dominated data centers for decades. An ARM64 (aarch64) image contains binaries compiled for ARM's 64-bit architecture, including AWS Graviton, Apple Silicon (M1/M2/M3), and Raspberry Pi 4/5. Understanding how these images coexist and how to build them correctly is essential for modern production deployments.

What Are Multi-Arch Images, Exactly?

Docker images are defined by manifests. A single-tag manifest can be a simple pointer to a single image configuration and its layers — or it can be a manifest list (also called a fat manifest or OCI image index) that contains pointers to multiple architecture-specific manifests. When you run docker pull, the Docker client sends its own OS and architecture information to the registry. The registry inspects the manifest list, finds the entry matching the client's platform, and serves only that specific image.

Here's a simplified view of a manifest list for a hypothetical myapp:1.0 tag:

myapp:1.0 (manifest list)
├── linux/amd64  → sha256:abc123... (actual image manifest + layers)
├── linux/arm64  → sha256:def456... (actual image manifest + layers)
└── linux/arm/v7 → sha256:ghi789... (32-bit ARM variant)

Each architecture variant contains entirely separate filesystem layers. The AMD64 image might include libssl.so compiled for x86_64, while the ARM64 image includes the same library compiled for aarch64. This is not emulation — it's native execution on each platform.

Why Architecture Choice Matters in Production

The architectural choice has profound implications across cost, performance, and operational complexity. Here are the key factors driving production decisions:

Cost Efficiency

AWS Graviton instances (powered by ARM64) typically offer 15-40% better price-performance than comparable x86 instances. For organizations running hundreds of containers, this translates to substantial cloud bill reductions. Google Cloud's Tau T2A instances and Azure's Ampere Altra offerings similarly promise ARM-native cost advantages. However, these savings only materialize if your containers run natively on ARM — running AMD64 images on ARM via emulation destroys the cost advantage and often performs worse than staying on x86.

Performance Characteristics

ARM64 processors excel at high-throughput, embarrassingly parallel workloads. They typically have more physical cores per socket and higher memory bandwidth. AMD64 processors often retain an edge in single-threaded performance and have decades of optimization in libraries like Intel MKL. Your workload profile matters enormously: a Node.js API server might see 20% better throughput on Graviton, while a numerical simulation relying on Intel-specific vector instructions could run slower.

Ecosystem Maturity

Most major open-source projects now publish multi-arch images. The official Docker images for PostgreSQL, Redis, Node.js, Python, and Go all support ARM64 natively. However, niche dependencies, older internal images, or third-party commercial software may only exist as AMD64. Before committing to an ARM migration, audit your entire dependency chain for architecture availability.

Development-Production Parity

Developers using Apple Silicon MacBooks run ARM64 containers natively. If your production runs AMD64, you have a mismatch. This can cause subtle bugs — a binary compiled for x86 might behave identically in tests (running under QEMU emulation on the Mac) but produce different performance profiles or even expose architecture-specific concurrency behaviors. Running the same architecture across dev and prod eliminates this class of risk.

Inspecting Image Architecture

Before diving into building multi-arch images, let's cover how to inspect what you already have. The docker manifest command is your primary tool:

# Inspect a remote image's manifest list
docker manifest inspect nginx:latest

# Output shows platform entries like:
# "platform": { "architecture": "amd64", "os": "linux" }
# "platform": { "architecture": "arm64", "os": "linux" }

# Inspect only the ARM64 variant
docker manifest inspect nginx:latest --platform linux/arm64

# For local images, use docker inspect with the architecture filter
docker inspect nginx:latest | jq '.[].Architecture'

# Check which platform a running container uses
docker inspect --format '{{.Platform}}' container_name

You can also use docker buildx imagetools for a cleaner formatted view:

docker buildx imagetools inspect node:20-alpine

This displays a tree of platforms and their corresponding digests, making it immediately obvious whether an image is single-arch or multi-arch.

Building Multi-Arch Images with Docker Buildx

The modern approach uses docker buildx, Docker's extended build system. Buildx supports creating multi-platform images through two strategies: native containerization (each architecture builds on its own native node) or QEMU emulation (a single builder node emulates multiple architectures).

Setting Up a Buildx Builder

# Create a new builder instance with multi-platform support
docker buildx create --name multi-arch-builder --driver docker-container --use

# Enable QEMU binfmt support for emulation (on Linux hosts)
docker run --privileged --rm tonistiigi/binfmt --install all

# Verify the builder can handle multiple platforms
docker buildx inspect --bootstrap

# Expected output shows supported platforms:
# linux/amd64, linux/arm64, linux/arm/v7, etc.

The --driver docker-container creates an isolated build environment separate from the default Docker daemon builder. This is crucial — the default builder has limited multi-platform support. The tonistiigi/binfmt step registers QEMU interpreters with the kernel, enabling transparent emulation of ARM binaries on an x86 host (and vice versa).

Creating a Multi-Arch Dockerfile

A well-structured Dockerfile for multi-arch builds avoids hardcoded architecture assumptions. Use ARG and build-time variables to handle platform-specific logic:

# syntax=docker/dockerfile:1

FROM --platform=$BUILDPLATFORM node:20-alpine AS builder

# TARGETARCH is automatically set by buildx (e.g., amd64, arm64)
ARG TARGETARCH
ARG TARGETOS

WORKDIR /app

# Copy package files and install dependencies
COPY package*.json ./
RUN npm ci --omit=dev

# If you need architecture-specific native modules,
# handle them explicitly
RUN if [ "$TARGETARCH" = "arm64" ]; then \
      echo "Building ARM64-specific optimizations"; \
    fi

# Copy source and build
COPY . .
RUN npm run build

# Final stage: use a platform-specific base image
FROM --platform=$TARGETPLATFORM node:20-alpine

ARG TARGETARCH

WORKDIR /app

# Copy built artifacts from the builder stage
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/package.json ./

# Architecture-specific runtime adjustments
RUN if [ "$TARGETARCH" = "arm64" ]; then \
      echo "ARM64 runtime configuration applied"; \
    fi

EXPOSE 3000
CMD ["node", "dist/main.js"]

Key built-in ARGs provided by buildx:

Building and Pushing Multi-Arch Images

# Build for multiple platforms and push directly to registry
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --tag yourregistry/myapp:1.0 \
  --push \
  .

# Build without pushing (loads only one platform to local Docker)
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --tag yourregistry/myapp:1.0 \
  --output type=tar,dest=myapp.tar \
  .

# Build and load only the local platform for testing
docker buildx build \
  --platform linux/arm64 \
  --tag myapp:local-test \
  --load \
  .

The --push flag is essential when building multiple platforms — Docker's local image store cannot hold multiple architecture variants for a single tag, so --load is limited to a single platform. For local testing of multi-platform behavior, build for your local architecture with --load and use --push for CI pipelines that publish to registries.

CI/CD Pipeline Integration

For production workflows, you'll integrate multi-arch builds into your CI/CD pipeline. Here's a GitHub Actions example:

# .github/workflows/docker-build.yml
name: Build Multi-Arch Docker Image

on:
  push:
    branches: [main]
    tags: ['v*']

jobs:
  build-and-push:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Set up QEMU
        uses: docker/setup-qemu-action@v3
        with:
          platforms: linux/amd64,linux/arm64

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3
        with:
          driver-opts: |
            image=moby/buildkit:latest

      - name: Login to Container Registry
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Extract metadata
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: ghcr.io/${{ github.repository }}
          tags: |
            type=ref,event=branch
            type=ref,event=tag
            type=sha,prefix={{branch}}-

      - name: Build and push
        uses: docker/build-push-action@v5
        with:
          context: .
          platforms: linux/amd64,linux/arm64
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

This pipeline uses Buildx's GitHub Actions cache backend (type=gha) to cache layers across builds, dramatically speeding up subsequent runs. The docker/setup-qemu-action installs QEMU emulation support, allowing a single GitHub-hosted x86 runner to build ARM64 images via emulation.

Native ARM Builds vs. QEMU Emulation

QEMU emulation during builds is convenient but slow. Building an ARM64 image on an x86 runner via emulation can take 3-10x longer than a native build. For production pipelines with tight SLAs, consider these alternatives:

# Option 1: Use separate native runners per architecture
# Create a buildx builder that spans multiple nodes
docker buildx create --name cross-cluster \
  --node arm-node --platform linux/arm64 \
  --node amd-node --platform linux/amd64 \
  --driver docker-container

# Each node runs on its native architecture hardware

# Option 2: Use AWS CodeBuild with Graviton instances
# or GitHub Actions ARM runners (available for larger plans)

For most teams, the QEMU approach works well — the slowdown is manageable for typical application images (under 500MB), and the infrastructure simplicity of a single CI runner type outweighs the build time cost. Reserve native ARM builders for monorepos with massive images or when build times exceed 30 minutes.

Testing Multi-Arch Images in Production

Before rolling out ARM64 to production, validate thoroughly:

# 1. Verify the manifest list was pushed correctly
docker buildx imagetools inspect yourregistry/myapp:1.0

# 2. Pull and run each architecture variant
docker run --rm --platform linux/amd64 yourregistry/myapp:1.0 --version
docker run --rm --platform linux/arm64 yourregistry/myapp:1.0 --version

# 3. Test in a staging environment with mixed architecture nodes
# Deploy to a cluster with both x86 and ARM nodes
# Monitor for crashes, performance regressions, memory leaks

# 4. Compare performance metrics between architectures
# Use tools like k6, wrk2, or artillery for load testing

Common pitfalls to watch for:

Image Tagging Strategies for Multi-Arch

Your tagging strategy affects how orchestrators schedule workloads. Several approaches exist:

Strategy 1: Single multi-arch tag — One tag covers all architectures. Kubernetes pulls the correct variant automatically based on node architecture. This is the simplest approach and works well for homogeneous deployments.

# Single tag, auto-resolved by kubelet
image: myregistry/myapp:1.0  # Works on both x86 and ARM nodes

Strategy 2: Architecture-specific tags — Explicit tags per architecture, useful when you need to pin specific versions per node pool or when debugging architecture-specific issues.

# Separate tags per architecture
myregistry/myapp:1.0-amd64
myregistry/myapp:1.0-arm64

Strategy 3: Combined approach — A multi-arch manifest list plus architecture-specific tags for rollback safety. This gives you the simplicity of auto-resolution with the safety of pinning when needed.

# Build multi-arch image
docker buildx build --platform linux/amd64,linux/arm64 \
  -t myregistry/myapp:1.0 \
  -t myregistry/myapp:1.0-amd64 --push .

# The 1.0-amd64 tag points only to the AMD64 variant
# The 1.0 tag resolves to the correct architecture at pull time

For production, I recommend Strategy 3. It provides operational flexibility: your deployment manifests use the generic tag for normal operations, but you retain architecture-specific tags for emergency rollbacks or when troubleshooting node-specific failures.

Handling Architecture-Specific Dependencies

Some applications have genuinely architecture-dependent code. Handle this explicitly rather than relying on runtime detection:

# Dockerfile fragment for architecture-specific dependencies
FROM --platform=$BUILDPLATFORM alpine:3.19 AS builder

ARG TARGETARCH

RUN apk add --no-cache curl

# Architecture-specific binary selection
RUN if [ "$TARGETARCH" = "arm64" ]; then \
      curl -o /usr/local/bin/special-tool \
        https://cdn.example.com/tool-arm64-v2.1.0; \
    else \
      curl -o /usr/local/bin/special-tool \
        https://cdn.example.com/tool-amd64-v2.1.0; \
    fi && \
    chmod +x /usr/local/bin/special-tool

# Verify the binary matches target architecture
RUN file /usr/local/bin/special-tool | grep -q "aarch64\|x86-64"

For interpreted languages (Node.js, Python, Ruby), pure-JS or pure-Python packages are architecture-agnostic. Only native extensions require attention. Audit your node_modules or site-packages for .node files or .so shared objects to identify architecture-sensitive packages.

Monitoring and Observability Considerations

When running mixed-architecture clusters, your observability stack must be architecture-aware:

# Example: Adding architecture label in Kubernetes
metadata:
  labels:
    app: myapp
    arch: {{ .Values.arch }}  # Set per-node-pool in Helm values

# In your application code, expose architecture as a metric
# Node.js example
const arch = process.arch;  // 'arm64' or 'x64'
metrics.counter('app.requests', { arch });

Migration Strategy: AMD64 to ARM64

Migrating production workloads from AMD64 to ARM64 requires a phased approach:

Phase 1: Audit — Inventory all container images in your registry. For each, determine if ARM64 variants exist. Flag images that are AMD64-only as blockers.

Phase 2: Build ARM64 variants — Update Dockerfiles and CI pipelines to produce multi-arch images for all your applications. This may require updating base images, fixing architecture-specific code, and rebuilding native dependencies.

Phase 3: Canary deployment — Deploy ARM64 variants to a small set of ARM nodes in your cluster. Run for at least a week, monitoring performance, error rates, and memory usage closely.

# Kubernetes canary with node affinity
apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp-canary-arm
spec:
  replicas: 2
  selector:
    matchLabels:
      app: myapp
      arch: arm64
  template:
    metadata:
      labels:
        app: myapp
        arch: arm64
    spec:
      affinity:
        nodeAffinity:
          requiredDuringSchedulingIgnoredByExecution:
            nodeSelectorTerms:
            - matchExpressions:
              - key: kubernetes.io/arch
                operator: In
                values: [arm64]
      containers:
      - name: myapp
        image: myregistry/myapp:1.0  # Multi-arch tag, resolves to ARM64 on ARM nodes
        env:
        - name: ARCH_LABEL
          value: "arm64"

Phase 4: Full rollout — Once the canary proves stable, expand ARM64 deployment across your ARM node pool. Maintain AMD64 images for x86 node pools during the transition.

Phase 5: Decommission AMD64 — After all workloads run successfully on ARM64, you can remove AMD64 node pools and optionally stop building AMD64 images (though maintaining both is recommended for flexibility).

Best Practices Summary

Common Troubleshooting Scenarios

"Image pulls but container exits immediately on ARM node" — This usually means the image is AMD64-only and the ARM node is trying to run it under QEMU emulation, which fails for this particular binary. Check with docker inspect --format '{{.Architecture}}' image:tag and ensure ARM64 support exists.

"Build succeeds locally on Apple Silicon but fails in CI" — Your CI runner is likely x86 and the Dockerfile has ARM64-specific assumptions. Use BUILDPLATFORM and TARGETPLATFORM correctly and test with --platform linux/amd64 locally on your Mac.

"Multi-arch build takes forever" — QEMU emulation of ARM on x86 for build stages is slow. Move compute-heavy build steps into a BUILDPLATFORM stage and only copy final artifacts into the TARGETPLATFORM stage. Use layer caching aggressively.

# Diagnose build performance
docker buildx build --platform linux/amd64,linux/arm64 \
  --progress=plain \
  --build-arg BUILDKIT_PROGRESS=plain \
  .  2>&1 | grep -E "^#\d+\s" | sort -t' ' -k3 -rn | head -20

# This shows which build steps consume the most time

Conclusion

Docker's multi-architecture image system is no longer a niche feature — it's a fundamental requirement for modern production deployments. The shift toward ARM64 in cloud computing, driven by cost efficiency and performance gains, makes understanding AMD64/ARM64 image management essential for every DevOps engineer. By adopting Buildx, structuring Dockerfiles with platform-aware ARGs, implementing robust CI/CD pipelines, and following a phased migration approach, you can confidently serve both architectures from a single image tag. The key insight is that multi-arch support is not just about supporting Apple Silicon developer laptops — it's about positioning your infrastructure to take advantage of whichever compute platform offers the best price-performance for your specific workloads, today and tomorrow.

🚀 Need a reliable AI agent for your project?

Deploy Hermes Agent in 10 minutes. Managed hosting, zero DevOps.

Get Started — $23.99/mo
← Back to all articles