Docker Tutorial · Building Images · Lesson 13 of 26
Build Arguments and Environment Variables
ARG for build-time values, ENV for runtime configuration, and why secrets belong in neither.
ARG versus ENV
ARG |
ENV |
|
|---|---|---|
| Available | During the build only | During the build and in running containers |
| Set with | docker build --build-arg NAME=value |
Dockerfile, or docker run -e NAME=value |
| Typical use | Versions, build modes | Configuration defaults |
Secrets
Neither is for secrets: ARG values appear in the image history and ENV values are stored in the image
config. Pass runtime secrets at run time (environment from a secrets manager, mounted files), and build-time
secrets with BuildKit secret mounts: RUN --mount=type=secret,id=npmrc ....
trap 'docker image rm -f rc-args:1 > /dev/null 2>&1' EXIT
cat > Dockerfile <<'EOF'
FROM alpine:3.24
ARG APP_VERSION=dev
ENV APP_VERSION=${APP_VERSION} LOG_LEVEL=info
CMD ["sh", "-c", "echo version=$APP_VERSION log_level=$LOG_LEVEL"]
EOF
docker build -q --build-arg APP_VERSION=1.4.2 -t rc-args:1 . > /dev/null
docker run --rm rc-args:1
docker run --rm -e LOG_LEVEL=debug rc-args:1
echo "visible in the image config: $(docker image inspect rc-args:1 --format '{{range .Config.Env}}{{println .}}{{end}}' | grep -E 'APP_VERSION|LOG_LEVEL' | tr '\n' ' ')"
Output
version=1.4.2 log_level=info version=1.4.2 log_level=debug visible in the image config: APP_VERSION=1.4.2 LOG_LEVEL=info
Run this on your computer — see “Get Started” for setup.
See Build variables and Build secrets.
Test yourself
Is ARG a safe way to pass an API token into a build?
Yes, ARG is encryptedNo: build arguments are recorded in the image history; use a BuildKit secret mountYes, if the image is privateOnly for short tokens
Show answer
Answer: No: build arguments are recorded in the image history; use a BuildKit secret mount
Secret mounts expose the secret only to one RUN step and never store it in a layer.