There are two main approaches depending on whether your base images already use multi-architecture manifest lists or are split into separate tagged images per architecture.

1. Use Official/Pre-built Multi-Architecture Base Images (Easiest) #

Most official Docker images (like ubuntu:latest, alpine:3.18, python:3.11) are already multi-architecture. This means they have a manifest list that maps the tag to individual images for each supported architecture (amd64, arm64, etc.).

When you run docker build on your host, Docker automatically pulls the version of the base image that matches your host's architecture. For example:

• On an amd64 machine, FROM ubuntu:latest will pull the amd64 variant.
• On an arm64 machine (like a Raspberry Pi or M1 Mac), it will pull the arm64 variant.

No extra configuration needed here—this works out of the box.

2. Switch Between Arch-Specific Base Images (For Custom/Split Images) #

If your base images are split into separate tags (e.g., whatever:amd64 and whatever:arm64), you can use Docker Buildx and build arguments to automatically select the right tag based on your host's architecture.

Step 1: Update Your Dockerfile #

Use the built-in BUILDPLATFORM variable (automatically set by Docker Buildx) to dynamically choose the base image tag:

# Default to amd64 if BUILDPLATFORM isn't set
ARG BUILDPLATFORM=linux/amd64
# Extract the architecture part (e.g., "amd64" from "linux/amd64")
ARG ARCH=${BUILDPLATFORM##*/}

# Use the arch-specific base image
FROM whatever:${ARCH}

# Rest of your Dockerfile instructions...

Step 2: Build With Docker Buildx #

Docker Buildx is the recommended tool for multi-platform builds, and it automatically populates the BUILDPLATFORM variable with your host's architecture. Run the build command like this:

docker buildx build -t your-image:latest .

This will pull whatever:amd64 on an amd64 host, and whatever:arm64 on an arm64 host.

Bonus: Create Your Own Multi-Architecture Manifest List #

If you want to simplify things for future builds, you can create a single tag (e.g., whatever:latest) that points to both your amd64 and arm64 base images. This turns your split images into a multi-architecture image that Docker can automatically detect:

1. Build each architecture-specific image:

   docker build --platform linux/amd64 -t whatever:amd64 .
   docker build --platform linux/arm64 -t whatever:arm64 .
   

2. Create a manifest list that combines them:

   docker manifest create whatever:latest whatever:amd64 whatever:arm64
   

3. Annotate each entry to specify the architecture:

   docker manifest annotate whatever:latest whatever:amd64 --os linux --arch amd64
   docker manifest annotate whatever:latest whatever:arm64 --os linux --arch arm64
   

4. Push the manifest list to your registry:

   docker manifest push whatever:latest
   

Now you can use FROM whatever:latest in your Dockerfile, and Docker will automatically pull the correct architecture variant for your host—just like official images.

内容的提问来源于stack exchange，提问作者ph0rex