You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Default value on TARGETPLATFORM always overrides #510
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.
Reacted by Quentin McGaw, Michael Gillis, William Arin, lorenzogrv, Lucas Willems, phlax, Adrien, Russell Dempsey, Cenk Altı, Yuanhao Ji and 3 more
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).
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:
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.
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.
Activity
tonistiigi commentedon Jan 20, 2021
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
TARGETPLATFORMfor a specific value for a specific Dockerfile stage it is not. Current logic is more constant to the regularARGbehavior 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).MarcelWaldvogel commentedon Jan 20, 2021
For the user it is not obvious that (a)
TARGETPLATFORMandBUILDPLATFORMare 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 buildneeds to be preserved while differentiating onTARGETPLATFORMorBUILDPLATFORMfordocker buildx. The seemingly obvious way of using defaults (e.g.,ARG TARGETPLATFORM=linux/amd64) does not work, as the values set bydocker buildxare already treated like defaults internally. The following construct is recommended as a workaround for these cases:tonistiigi commentedon Jan 27, 2021
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.MarcelWaldvogel commentedon Feb 2, 2021
I tried to shorten the explanation as much as possible. I hope it meets your expectations.
Fix backbards
storage: compile spdk for arm64
storage: compile spdk for arm64
storage: compile spdk for arm64
storage: compile spdk for arm64
storage: compile spdk for arm64
storage: compile spdk for arm64
storage: compile spdk for arm64
4 remaining items
tonistiigi commentedon May 15, 2024
When you set default value on an ARG, you can expect it to be overridden by
docker buildx build --build-arg ...command.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.
cenkalti commentedon May 16, 2024
Sorry, I forgot to mention. I am talking specifically about
TARGETOSandTARGETARCHargs.For example, if there is default value set on
TARGETARCH, it doesn't matter what I pass in--platformand always the default value is used.If I remove the default value, it works as expected.
fix: remove hardcoded TARGETARCH/TARGETOS defaults that break arm64 b…
CH3CHO commentedon May 22, 2026
Any progress on this issue? Looks like I'm not the only one who encounters this issue.
beanscg commentedon Jun 10, 2026
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:
docker/buildx; repo licenseApache-2.0; no assignee; 8 comments.A good acceptance check would be a narrow public change that directly exercises the issue's reported boundary.
No PR opened from this pass.
Fix multi-arch Docker build: per-leg Go toolchain + pkg-config
locker95 commentedon Aug 16, 2026
left a note on the multi-platform page so the ARG default vs --platform trap is documented: docker/docs#25847
MarcelWaldvogel commentedon Aug 17, 2026
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.
Fix BUILDPLATFORM fallback to not clobber real buildx cross-builds
Fix Docker Compose quick start on Apple Silicon and buildx-less hosts (…
fix(build): the arm64 legs were amd64 — TARGETARCH had a default
run-multiplexed-agent-workspaces: fix TARGETARCH crash under classic …
Bind OIDC token handoff to the browser; tighten config and devcontainer
Fix: On ARM64 hosts, the explicit TARGETARCH=amd64 default overrides …