BuildKit & Multi-Arch

This page explains two things you have already been using without noticing (BuildKit), and one thing you will need the moment you build on an Apple Silicon Mac and deploy to a typical cloud server (multi-arch).

BuildKit

Every docker build you ran on the last two pages already used BuildKit — Docker’s modern build engine. It has been the default since Docker Engine 23, so there was nothing extra to turn on.

Compared to the older build engine, BuildKit:

Builds independent layers in parallel instead of strictly one at a time, when your Dockerfile allows it
Skips stages a multi-stage build does not actually need for the final image
Caches more intelligently, so unrelated changes invalidate less of the cache

You do not need to configure anything here — this section exists so you know what BuildKit is when you see it mentioned in Docker’s output or documentation.

The Problem Multi-Arch Solves

CPUs come in different architectures — the two you will run into most are:

amd64 (also called x86_64) — most traditional cloud servers, most Windows and Intel/AMD machines
arm64 (also called aarch64) — Apple Silicon Macs (M1, M2, M3, M4), and increasingly common ARM-based cloud servers, since they tend to be cheaper to run

An image built on one architecture does not run on the other. If you build my-next-app on an Apple Silicon Mac and push it, a plain amd64 cloud server will fail to run it.

This is a real, common surprise. “It worked on my Mac but the server won’t run it” is often an architecture mismatch, not a bug in your code.

Building for Multiple Architectures

docker buildx is the tool that builds one image for several architectures at once.

Check buildx is available

Terminal


docker buildx version

Docker Desktop includes this already. If you are on Linux without Docker Desktop, you may need to install the buildx plugin separately.

Create a builder that supports multiple platforms

Terminal


docker buildx create --name multiarch-builder --use
docker buildx inspect --bootstrap

You only need to do this once per machine.

Build and push for both architectures

Terminal


docker buildx build --platform linux/amd64,linux/arm64 -t your-username/my-next-app:1.0 --push .

--platform linux/amd64,linux/arm64 — build for both architectures in one command
--push — required for multi-platform builds; Docker cannot load more than one architecture into your local docker images at once, so the result goes straight to the registry

Anyone who now runs docker run your-username/my-next-app:1.0 gets the correct version for their own machine automatically — Docker picks the matching architecture behind the scenes.

When You Actually Need This

You develop on an Apple Silicon Mac and deploy to a standard amd64 VPS or cloud server.
Your team has a mix of Intel/AMD and Apple Silicon machines.
You specifically want to support cheaper arm64 cloud servers.

If everyone on the project uses the same architecture end to end, a plain docker build (from the last page) is enough — multi-arch builds add build time for a benefit you would not use.

Quick Check

Can you explain why an image built on an Apple Silicon Mac might fail on a typical cloud server?
Do you know what --platform linux/amd64,linux/arm64 does?
Can you explain why multi-platform builds require --push?

Next → .dockerignore