If you've been building Docker images, you already know docker build. But there's also docker buildx — and it's worth knowing the difference, because in production it makes a huge impact.
docker build?docker build is the basic command for building images. It builds an image only for the architecture of the machine you're running it on. If you're on an amd64 machine (Intel/AMD) — your image will only work on amd64.
docker build -t my-app .
Simple, fast, works. But there's one problem — what if your server has a different architecture?
More and more servers (and computers) run arm64 processors — Oracle Cloud Free Tier gives ARM machines, Apple Silicon (M1/M2/M3) is also ARM. An image built for amd64 won't run natively on arm64.
You can work around this with emulation, but it's slow and inefficient. A better solution is buildx.
docker buildx?buildx is a Docker extension that lets you build images for multiple architectures at once — a so-called multi-arch build. One image, many platforms.
docker buildx build \
--platform linux/amd64,linux/arm64 \
-t registry.racis.dev/my-app:latest \
--push \
.
Docker takes care of making the image work on both Intel/AMD and ARM. When you docker pull, the correct variant for the current system is pulled automatically.
First, create a builder — the default driver doesn't support multi-arch:
docker buildx create --name mybuilder --use
docker buildx inspect --bootstrap
Now you can build for multiple platforms:
docker buildx build \
--platform linux/amd64,linux/arm64 \
-t my-app:v1 \
-t my-app:latest \
--push \
.
The --push flag pushes the image to the registry immediately — for multi-arch it's required, because a manifest list can't be stored locally.
| Situation | Use |
|---|---|
| Building locally for testing | docker build |
| Server has the same architecture as your machine | docker build |
| Server has a different architecture (e.g. ARM Oracle Cloud) | docker buildx |
| Publishing an image publicly | docker buildx |
| Want the image to work everywhere | docker buildx |
docker build is simpler and sufficient for local development. But if you're building images that go to a server — especially ARM — buildx is a must-have. One build, all platforms.