Docker build args

Topic: Containers core

Use ARG in Dockerfile to pass build-time variables; set with --build-arg. Use for version pins or build variants. Do not use ARG for runtime secrets. Use this when you need parameterized builds.

Intent: How-to

Quick answer

  • Dockerfile: ARG VERSION=1.0. RUN use $VERSION. Build: docker build --build-arg VERSION=2.0 . ARG is not available at runtime.
  • Use for base image tags, package versions, or build flags. Default in ARG is used if --build-arg not passed.
  • Do not pass secrets with --build-arg; they end up in image layers. Use multi-stage and runtime injection for secrets.

Prerequisites

Steps

  1. Declare ARG

    ARG VERSION=1.0 at top or before first use. Use ${VERSION} in RUN or COPY as needed.

  2. Pass at build

    docker build --build-arg VERSION=2.0 -t app . Or in compose: build args: VERSION: 2.0.

  3. Verify

    Inspect image or run container to confirm version or artifact matches passed arg.

Summary

Use ARG in Dockerfile and —build-arg at build time for version or variant; do not use for secrets.

Prerequisites

Steps

Step 1: Declare ARG

Add ARG with optional default; use in RUN/COPY.

Step 2: Pass at build

Use —build-arg or compose build args.

Step 3: Verify

Confirm build output matches passed args.

Verification

  • Image reflects build args; no secrets in layers.

Troubleshooting

ARG not set — Pass —build-arg or set default. Secret in layer — Remove; use runtime injection.

Next steps

Continue to