Skip to content

Default value on TARGETPLATFORM always overrides #510

Open

Description

@MarcelWaldvogel

What I want to achieve

I have a project that I want to be able to build both with docker build (for compatibility) and docker buildx --platform and which requires TARGETPLATFORM to make a difference in the build process. As TARGETPLATFORM is not set by docker build, the default value option to ARG seemed the right choice.

What I expect

Given the following Dockerfile,

FROM debian:buster-slim
ARG TARGETPLATFORM=linux/amd64
RUN echo $TARGETPLATFORM; exit 1

I expect docker build . on all architectures to output linux/amd64 (the legacy compatibility case).

When running docker buildx --builder docker-multiarch --platform linux/386 ., the output should be linux/386.

What I get

On platform linux/amd64, docker buildx --builder docker-multiarch --platform linux/386 ., outputs linux/amd64 instead of linux/386.

Removing the default value solves this: docker buildx --builder docker-multiarch --platform linux/386 . results in linux/386 with Dockerfile:

FROM debian:buster-slim
ARG TARGETPLATFORM
RUN echo $TARGETPLATFORM; exit 1

However, docker build . results in an empty/undefined TARGETPLATFORM.

(For ARGs set with --build-arg on the command line, defaults behave as expected.)

System setup

  • Ubuntu 20.10
  • Docker 19.03.13
  • Buildx 0.4.1 or 0.5.1 (tested with both)

Workaround

The following Dockerfile results in the expected behavior:

FROM debian:buster-slim
ARG TARGETPLATFORM
ENV TARGETPLATFORM=${TARGETPLATFORM:-linux/amd64}
RUN echo $TARGETPLATFORM; exit 1

However, this (a) defeats the purpose of the default value and (b) causes endless debugging sessions, as it violates the documentation of ARG and TARGETPLATFORM.

Activity

  1. tonistiigi commented on Jan 20, 2021

    @tonistiigi
    Member

    For the builtin args, default value is set if none is set by the user. For your use case it makes sense to overwrite the user's default value but for some others that want to fix TARGETPLATFORM for a specific value for a specific Dockerfile stage it is not. Current logic is more constant to the regular ARG behavior and not a special exception. And as you say, there is a workaround for setting the value if it is empty (for non-buildkit builders).

  2. MarcelWaldvogel commented on Jan 20, 2021

    @MarcelWaldvogel
    Author

    For the user it is not obvious that (a) TARGETPLATFORM and BUILDPLATFORM are only defaults, not actual values, (b) that explicit defaults override the implicit ones, and (c) that this type of workaround is needed/possible.

    As I take your response as "WONTFIX: works as designed", how about changing the documentation to add the following (as there are no footnotes in Markdown, something along the following lines should be placed right before "High-level build options"):


    Backward compatibility

    Sometimes, backward compatibility of the build process to docker build needs to be preserved while differentiating on TARGETPLATFORM or BUILDPLATFORM for docker buildx. The seemingly obvious way of using defaults (e.g., ARG TARGETPLATFORM=linux/amd64) does not work, as the values set by docker buildx are already treated like defaults internally. The following construct is recommended as a workaround for these cases:

    ARG TARGETPLATFORM
    ENV TARGETPLATFORM=${TARGETPLATFORM:-linux/amd64}
  3. tonistiigi commented on Jan 27, 2021

    @tonistiigi
    Member

    Yes, docs can always be improved (via PR). If you look at the current docs https://docs.docker.com/engine/reference/builder/#automatic-platform-args-in-the-global-scope it is defined that these parameters are defined in the global scope and global scope working like this is already documented.

    We don't want to spend that much time describing what happens on other builders that users shouldn't care about but just encourage them to update. But adding a line reminding people that ${TARGETPLATFORM:-linux/amd64} can be used in place of the variable if you worry that Dockerfile might be run on a builder without this feature seems harmless.

  4. MarcelWaldvogel commented on Feb 2, 2021

    @MarcelWaldvogel
    Author

    I tried to shorten the explanation as much as possible. I hope it meets your expectations.

  5. 4 remaining items

  6. tonistiigi commented on May 15, 2024

    @tonistiigi
    Member

    When I set a default value on an ARG, I expect it to be overriden by docker buildx build --platform= command.

    When you set default value on an ARG, you can expect it to be overridden by docker buildx build --build-arg ... command.

    The following Dockerfile results in the expected behavior:
    FROM debian:buster-slim
    ARG TARGETPLATFORM
    ENV TARGETPLATFORM=${TARGETPLATFORM:-linux/amd64}
    RUN echo $TARGETPLATFORM; exit 1

    For clarity, "-linux/amd64" in that Dockerfile never gets called or has any impact on buildkit-based builder, no matter what configuration was passed to the build.

  7. cenkalti commented on May 16, 2024

    @cenkalti

    Sorry, I forgot to mention. I am talking specifically about TARGETOS and TARGETARCH args.

    For example, if there is default value set on TARGETARCH, it doesn't matter what I pass in --platform and always the default value is used.

    FROM debian:buster-slim
    ARG TARGETARCH=amd64
    RUN echo $TARGETARCH; exit 1
    $ docker build --platform linux/arm64 .
    ...
     > [2/2] RUN echo amd64; exit 1:

    If I remove the default value, it works as expected.

    FROM debian:buster-slim
    ARG TARGETARCH
    RUN echo $TARGETARCH; exit 1
    $ docker build --platform linux/arm64 .
    ...
     > [2/2] RUN echo arm64; exit 1:
  8. CH3CHO commented on May 22, 2026

    @CH3CHO

    Any progress on this issue? Looks like I'm not the only one who encounters this issue.

  9. beanscg commented on Jun 10, 2026

    @beanscg

    Bean Labs took a public-source pass on this issue.

    The narrowest useful next step looks like: Offer to identify the exact docs page and propose a minimal wording/example clarification before any patch.

    Public evidence checked:

    • Open public issue in docker/buildx; repo license Apache-2.0; no assignee; 8 comments.
    • Labels: kind/docs, area/dockerfile, area/docs.
    • Locator from title/labels; future commenter should ask for preferred docs/test file before drafting.

    A good acceptance check would be a narrow public change that directly exercises the issue's reported boundary.

    No PR opened from this pass.

  10. locker95 commented on Aug 16, 2026

    @locker95

    left a note on the multi-platform page so the ARG default vs --platform trap is documented: docker/docs#25847

  11. MarcelWaldvogel commented on Aug 17, 2026

    @MarcelWaldvogel
    Author

    The text of the documentation PR docker/cli#2956 I submitted in early 2021 is still here, even though the PR was closed in 2024.
    docker/cli@564f8ce

    Feel free to adapt/reopen it.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions