9.3.1.3 Compose Build Args

Compose build args pass build-time variables into the Dockerfile build process through the args field within a service's build configuration, mirroring the --build-arg flag available when building an image directly with the Docker CLI.

Passing a Build Argument

Each argument specified under args becomes available to the Dockerfile's own ARG declarations during the build.

services:
  api:
    build:
      context: .
      args:
        - NODE_VERSION=20
        - BUILD_ENV=production

ARG NODE_VERSION
ARG BUILD_ENV
FROM node:${NODE_VERSION}-alpine
ENV NODE_ENV=${BUILD_ENV}

Why Build Args Differ From Runtime Environment Variables

A build argument is only available during the actual build process — unless explicitly carried forward into an ENV instruction within the Dockerfile, it has no effect on the running container's environment at all, distinguishing it clearly from the service's own environment field.

ARG VERSION
RUN echo "Building version ${VERSION}"

This argument influences the build process itself but doesn't automatically become available inside the resulting container at runtime.

Referencing a Host Environment Variable as a Build Arg's Value

A build argument's value can be sourced from the host's own environment, useful for build-time values that shouldn't be hardcoded directly into the Compose file.

services:
  api:
    build:
      context: .
      args:
        - GIT_COMMIT=${GIT_COMMIT}

export GIT_COMMIT=$(git rev-parse HEAD)
docker compose build api

Why Compose Build Args Matter

Build arguments provide a way to customize the actual image-building process itself — selecting versions, embedding build metadata, toggling build-time behavior — distinct from configuring the resulting container's runtime behavior, making them valuable for builds that need to vary based on external input.