Build X86 Docker images on M1

Posted On: February 20, 2024

In a recent project I needed to build an X86-64 (AMD64) Docker image and push it to AWS Elastic Container Registry (ECR). The problem was that I use a Mac with an Apple Silicon M1 chip. This led to an error when I was trying to run the ECS Task, since the rest of the infrastructure is built on AMD64. Luckily, I was able to figure out a way to build this image for an AMD64 architecture and get it deployed to AWS. Here’s how I did it using Docker Buildx.

TL;DR: Build AMD64 on M1 (Docker Buildx)

docker buildx create --use
docker buildx build --platform linux/amd64 -t <repo>:<tag> --load .

This builds a linux/amd64 image on Apple Silicon (M1/M2/M3) and loads it into your local Docker daemon.

Docker Buildx

If you’re bothering to read this, I’m sure you’ve ran the docker build command before. Docker buildx is a very similar command which allows you to build cross-architecture images. It provisions a Moby BuildKit container which is what provides the additional functionality. But how do you use it?

Enabling buildx

UPDATE*
In modern version of Docker Desktop, buildx is enabled by default. But if for some reason you don’t have it enabled, below are the instructions for enabling it.

Before we get started we’ll need to enable the docker buildx command. If you use Docker Desktop you can enable this by going to settings -> Features in development -> Experimental Features and click the Access experimental features checkbox. Then click Apply & restart. If you don’t use Docker Desktop there are plenty of instructions out there on how to install it for your system. Once you have it installed, if you type docker buildx in the terminal it should spit out a bunch of information about the command. The first command we’re going to look at is create.

Create and use a Buildx builder

First, create a Buildx builder and set it as the active builder:

docker buildx create --use

This spins up a BuildKit container (usually moby/buildkit) that enables cross-architecture builds. In most cases, you only need to do this once.

You can confirm Buildx is available by running:

docker buildx ls

Build the image for linux/amd64

Once Buildx is ready, you can build your image for the amd64 architecture by specifying the platform explicitly:

docker buildx build --platform linux/amd64 -t my-image:latest --load .

Key points:

  • --platform linux/amd64 ensures the image is built for x86-64 (AMD64), even on Apple Silicon.
  • --load loads the resulting image into your local Docker daemon so it behaves like a normal docker build result.

At this point, you have a locally available amd64 image that can be run, tagged, or pushed like any other Docker image.

If you want to double-check that the image was built correctly, you can inspect it:

docker image inspect my-image:latest \
  --format '{{.Architecture}}/{{.Os}}'

You should see:

amd64/linux

Pushing an AMD64 Image to AWS ECR

In my case, the reason I needed an amd64 image was to deploy it to AWS Elastic Container Registry (ECR) and run it in ECS, which expects amd64 images by default.

If you’re already familiar with pushing images to ECR, you can skip this section.

Get ECR push commands from AWS

To push an image to ECR:

  1. Log into the AWS Console
  2. Navigate to Elastic Container Registry (ECR)
  3. Create a repository if you don’t already have one
  4. Open the repository and click “View push commands”

AWS will provide a set of commands that:

  • Authenticate Docker with ECR
  • Tag your image correctly
  • Push the image to the repository

These commands assume:

  • The AWS CLI is installed
  • You are authenticated with AWS

The AWS documentation linked in the popup walks through this setup if you haven’t done it before.

Why I use --load instead of --push

You may see examples that use --push directly with docker buildx build. In my case, I ran into authentication issues with Buildx pushing directly to ECR.

Using --load allowed me to:

  • Build the amd64 image locally
  • Push it using the standard ECR workflow provided by AWS

This approach has been more reliable for me, especially when working across different AWS accounts or credential setups.

In Closing

Well, I hope this helps! And if you are interested in learning more about AWS, Docker, or Full Stack Web Development in general, be sure to check out my other posts here.