If you're building Docker images on an ARM-based machine (like an Apple Silicon Mac), you've probably seen this at some point:

no matching manifest for linux/amd64 in the manifest list entries

Everything works locally.
You push the image.
You deploy to a cloud VM.

Boom. It fails.

Why?

Because Docker images are not automatically cross-architecture.

The Real Issue: ARM vs AMD64

Modern Macs (M1/M2/M3) build images for:

linux/arm64

Most cloud servers (DigitalOcean, AWS, Azure, etc.) run:

linux/amd64

When you run:

docker build -t myapp .

Docker builds for your native architecture only.

So your registry ends up with:

linux/arm64 only

When your amd64 server tries to pull it, Docker can't find a compatible image.

The Fix: Docker Buildx + Multi-Arch Builds

Docker provides buildx to build images for multiple architectures and push a single tag that contains both.

This is what makes your image truly portable.

Step 1 — Create a Multi-Arch Builder (One-Time Setup)

You only need to do this once on your machine:

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

What this does:

Creates a new builder instance
Enables cross-compilation support
Bootstraps QEMU for emulation
Makes it the active builder

You do not need to recreate this every time.

Step 2 — Build and Push Multi-Arch Image

Now build and push in one command:

docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t registry.digitalocean.com/dev-hound-containers/dev-hound-blog:latest \
  --push \
  .

What this does:

Builds one image for linux/amd64
Builds one image for linux/arm64
Creates a manifest list
Pushes everything to the registry

Your single tag (latest) now contains both architectures.

When a server pulls it, Docker automatically selects the correct one.

If You Only Deploy to AMD64 Servers

If your production environment is amd64 (most VPS providers), you can simplify:

docker buildx build \
  --platform linux/amd64 \
  -t registry.digitalocean.com/dev-hound-containers/dev-hound-blog:latest \
  --push \
  .

This avoids multi-arch complexity and builds only what production needs.

Verify the Architectures in Your Image

To inspect what platforms are included:

docker buildx imagetools inspect registry.digitalocean.com/dev-hound-containers/dev-hound-blog:latest

You should see something like:

Name:      registry.digitalocean.com/...
MediaType: application/vnd.docker.distribution.manifest.list.v2+json

Manifests:
  Platform: linux/amd64
  Platform: linux/arm64

If you only see one architecture, you did not build multi-arch.

What Professionals Do

In production environments, teams typically:

Build images in CI (not on laptops)
Always target linux/amd64
Or build multi-arch automatically
Push versioned tags instead of relying on latest

Example with version tagging:

docker buildx build \
  --platform linux/amd64 \
  -t registry.digitalocean.com/dev-hound-containers/dev-hound-blog:2026-02-25-1 \
  --push \
  .

Then deploy that specific tag.

Mental Model Upgrade

Docker gives you:

OS portability
Environment portability

It does not automatically give you:

CPU architecture portability

That requires:

--platform

Once you understand that, ARM vs AMD64 stops being mysterious.

TL;DR

If you're on Apple Silicon and deploying to cloud VMs:

Always build with:

docker buildx build --platform linux/amd64 --push ...

Or build multi-arch if you want full portability.

Welcome to the ARM era.

Notes, Thoughts & Ideas

Authoring Multi-Architecture Dockers