Forcing docker to use linux/amd64 platform by default on macOS

Question

Current beta version of docker requires you to specify a --platform=linux/amd64 each time you need to build or run an amd64 image/container.

The documentation mentions

When running an image with multi-architecture support, docker will automatically select an image variant which matches your OS and architecture.

The documentation does not specify a way to alter this automatic behaviour using env variables. It seems to ignore both BUILDPLATFORM and TARGETPLATFORM.

Is there any other way to force docker to run all build and run commands with a platform linux/amd64 instead of linux/arm64/v8 by default on macOS running on apple-silicon?

Eduardo Cuomo · Accepted Answer · 2023-02-15 14:31:06Z

438

You can set the environment variable DOCKER_DEFAULT_PLATFORM:

export DOCKER_DEFAULT_PLATFORM=linux/amd64

edited Feb 15, 2023 at 14:31

Eduardo Cuomo

19.2k7 gold badges121 silver badges98 bronze badges

answered Apr 1, 2021 at 8:23

Beppe C

14.4k2 gold badges23 silver badges49 bronze badges

Sign up to request clarification or add additional context in comments.

4 Comments

Vojtech Letal Over a year ago

This was introduced in v19.03.0 in 03/2019. I do not understand how I missed that.

Max Cascone Over a year ago

This is great and it works, but i've also found I need to unset it when creating clusters with kind. If you get errors like docker: Cannot overwrite digest sha256:..., try unsetting the DOCKER_DEFAULT_PLATFORM var.

slai-nick Over a year ago

is it possible to configure this option within a docker configuration file rather than a shell environment?

starwarswii Mar 4 at 15:27

@jeffmcc that link is dead now as well. it's here: blog.driftingruby.com/docker-builds-are-slow-on-m1

OneCricketeer · Accepted Answer · 2025-12-08 13:18:14Z

314

Docker images built with Apple Silicon (or another ARM64 based architecture) can create issues when deploying the images to a Linux or Windows based AMD64 environment (e.g. AWS EC2, ECS, etc.). For example, you may try to upload your docker image made on the M1 chip to an AWS ECR repository and it fails to run. Therefore, you need a way to build AMD64 based images on the ARM64 architecture, whether it's using docker build (for individual images) or docker-compose build (e.g. for multi-image apps running in a Docker Compose network).

For building single docker images: Set your environment variable using the command line or modifying your .bashrc or .zshenv file as suggested in the accepted answer.

export DOCKER_DEFAULT_PLATFORM=linux/amd64

Alternatively, in the Dockerfile, include the following flag in the FROM command (for a multi-stage Dockerfile build, the flag is only needed for the first stage):

FROM --platform=linux/amd64 python:3.7-alpine

For building images as part of a docker-compose build, include the platform: linux/amd64 for each service. For example:

  services:  
    frontend:  
      platform: linux/amd64
      build: frontend  
      ports:
        - 80:80  
      depends_on:
        - backend  
    backend:  
      platform: linux/amd64
      build: backend

edited Dec 8 at 13:18

OneCricketeer

193k20 gold badges147 silver badges277 bronze badges

answered Oct 19, 2021 at 19:11

WildGoose

3,1511 gold badge8 silver badges4 bronze badges

7 Comments

Vojtech Letal Over a year ago

What is the source of the "issues"? You mean like accidentally running ARM image on AMD64 platforms? Is it even possible?

Kim Stacks Over a year ago

I prefer this solution (I'm using docker-compose) over the accepted answer of setting env variable on the host OS

dotslash Over a year ago

This works great. I'm using docker-compose to build linux/amd64 applications on a M1 MacBook Pro.

ekydfejj Over a year ago

This is pretty old, but this points to the best option IMO, i chose to keep platform in docker-compose.yaml but adding --platform=linux/amd64 do the FROM section of DockerFile seemed to be the best fix.

juntunen Over a year ago

I prefer putting this in the docker-compose.yml file as well. This saved me. Thanks a lot!

|

Eduardo Cuomo · Accepted Answer · 2023-02-15 14:30:02Z

63

You don't need to export the env variable as mentioned in one of the answers, you can run it as part of the command a single time by doing:

DOCKER_DEFAULT_PLATFORM=linux/amd64 docker-compose build

Keep in mind that if you've already downloaded the image for a different platform, docker will keep using that image no matter what platform you specify as your default, you would delete the image using docker image rm your_img first to fix that.

edited Feb 15, 2023 at 14:30

Eduardo Cuomo

19.2k7 gold badges121 silver badges98 bronze badges

answered Nov 4, 2021 at 13:02

Timo Huovinen

56k34 gold badges163 silver badges150 bronze badges

2 Comments

Huge Over a year ago

mind that if you system requires sudo to run docker, you have to put the PLATFORM into the sudo, note before that. Correct example:

sudo DOCKER_DEFAULT_PLATFORM=linux/amd64 docker run --gpus all --shm-size 1g -p 8080:80 ghcr.io/huggingface/text-generation-inference:1.1.0

Perhaps that is obvious, but some script kiddies can appreciate.

dQw4w9WyXcQ Over a year ago

best solution when using compose ty

Eduardo Cuomo · Accepted Answer · 2023-02-15 14:30:39Z

28

You can use buildx (mobi) which suipport cli for platform.

docker buildx build --platform linux/amd64 .

edited Feb 15, 2023 at 14:30

Eduardo Cuomo

19.2k7 gold badges121 silver badges98 bronze badges

answered Feb 25, 2022 at 5:20

Max Barrass

3,3221 gold badge22 silver badges14 bronze badges

2 Comments

Max Barrass Over a year ago

Here is my Debian ARM docker build github.com/aem-design/docker-tini/blob/debian-arm/build.ps1 and here is the pipeline github.com/aem-design/docker-tini/blob/debian-arm/.github/…. Its used here github.com/aem-design/docker-oracle-jdk/blob/jdk8-arm/….

Max Barrass Over a year ago

Well buildx is an extra addition to docker hence ive mentioned it. But for Docker as is the docs on ENV variables are here docs.docker.com/engine/reference/commandline/cli/… and they seem to be clear and to the point without any snark remarks.

Christian Chiama · Accepted Answer · 2022-06-25 07:58:50Z

19

you can set

export DOCKER_DEFAULT_PLATFORM=linux/amd64

in a .zshrc file for Mac M1

answered Jun 25, 2022 at 7:58

Christian Chiama

2442 silver badges5 bronze badges

1 Comment

OneCricketeer Dec 8 at 13:15

This would affect all containers, though

Alessandro Argentieri · Accepted Answer · 2023-06-07 08:44:12Z

5

Add this snipped to your ~/.zshrc and ~/.bashrc. It allows you not to repeat the flag anytime you perform a docker run command:

# useful only for Mac OS Silicon M1, 
# still working but useless for the other platforms
docker() {
  if [[ `uname -m` == "arm64" ]] && [[ "$1" == "run" || "$1" == "build" ]]; then
     /usr/local/bin/docker "$1" --platform linux/amd64 "${@:2}"
  else
     /usr/local/bin/docker "$@"
  fi
}

answered Jun 7, 2023 at 8:44

Alessandro Argentieri

3,2934 gold badges39 silver badges72 bronze badges

Comments

Eduardo Cuomo · Accepted Answer · 2023-02-15 14:30:18Z

2

You can add in your docker-compose.yaml:

services:
  service_name:
    environment:
      - DOCKER_DEFAULT_PLATFORM=linux/amd64

edited Feb 15, 2023 at 14:30

Eduardo Cuomo

19.2k7 gold badges121 silver badges98 bronze badges

answered Jun 8, 2022 at 8:59

ekimas

5568 silver badges16 bronze badges

3 Comments

schwaller Over a year ago

That doesnt really work for me. I think the "platform" is the way to go.

OneCricketeer Over a year ago

This would work for docker-in-docker. Not clear otherwise how this variable would be made available to the system docker daemon

Matthew Setter Over a year ago

I just tried this and it had no effect.

Collectives™ on Stack Overflow

Forcing docker to use linux/amd64 platform by default on macOS

7 Answers 7

4 Comments

7 Comments

2 Comments

2 Comments

1 Comment

Comments

3 Comments

Your Answer

Linked

Hot Network Questions

Collectives™ on Stack Overflow

7 Answers 7

4 Comments

7 Comments

2 Comments

2 Comments

1 Comment

Comments

3 Comments

Your Answer

Sign up or log in

Post as a guest

Linked

Related