What are Docker build arguments (ARG)?

ARG defines build-time variables that can be passed to the Dockerfile during docker build with --build-arg. Unlike ENV (persists at runtime), ARG values are only available during the build process — they don't exist in the running container. Syntax in Dockerfile: ARG NODE_VERSION=20\nFROM node:${NODE_VERSION}-alpine. Pass at build time: docker build --build-arg NODE_VERSION=18 .. Default value if not provided: ARG PORT=3000. Using ARG after FROM: ARG is scoped to the stage it's defined in — if you need it across FROM stages, re-declare it after each FROM. Use cases: (1) Parameterize base image versions; (2) Pass build environment (CI build number, git SHA for labels); (3) Feature flags at build time; (4) Registry and image paths for inner images. ARG and cache: changing a build arg value invalidates the cache from that ARG onward. CRITICAL security warning: ARG values ARE visible in docker history — never use ARG for secrets (passwords, API keys). Use BuildKit secrets instead: RUN --mount=type=secret,id=mysecret cat /run/secrets/mysecret. ARG vs ENV: use ARG for build-time configuration; ENV for runtime configuration. You can convert ARG to ENV: ARG APP_VERSION\nENV APP_VERSION=${APP_VERSION}.