Build Variables: ARG vs ENV

--- title: Build variables linkTitle: Variables weight: 20 description: Using build arguments and environment variables to configure builds keywords: build, args, variables, parameters, env, environment variables, config aliases: - /build/buildkit/color-output-controls/ - /build/building/env-vars/ - /build/guide/build-args/ --- In Docker Build, build arguments (`ARG`) and environment variables (`ENV`) both serve as a means to pass information into the build process. You can use them to parameterize the build, allowing for more flexible and configurable builds. > [!WARNING] > > Build arguments and environment variables are inappropriate for passing secrets > to your build, because they're exposed in the final image. Instead, use > secret mounts or SSH mounts, which expose secrets to your builds securely. > > See [Build secrets](./secrets.md) for more information. ## Similarities and differences Build arguments and environment variables are similar. They're both declared in the Dockerfile and can be set using flags for the `docker build` command. Both can be used to parameterize the build. But they each serve a distinct purpose. ### Build arguments Build arguments are variables for the Dockerfile itself. Use them to parameterize values of Dockerfile instructions. For example, you might use a build argument to specify the version of a dependency to install. Build arguments have no effect on the build unless it's used in an instruction. They're not accessible or present in containers instantiated from the image unless explicitly passed through from the Dockerfile into the image filesystem or configuration. They may persist in the image metadata, as provenance attestations and in the image history, which is why they're not suitable for holding secrets. They make Dockerfiles more flexible, and easier to maintain. For an example on how you can use build arguments, see [`ARG` usage example](#arg-usage-example). ### Environment variables Environment variables are passed through to the build execution environment, and persist in containers instantiated from the image. Environment variables are primarily used to: - Configure the execution environment for builds - Set default environment variables for containers Environment variables, if set, can directly influence the execution of your build, and the behavior or configuration of the application. You can't override or set an environment variable at build-time. Values for environment variables must be declared in the Dockerfile. You can combine environment variables and build arguments to allow environment variables to be configured at build-time. For an example on how to use environment variables for configuring builds, see [`ENV` usage example](#env-usage-example). ## `ARG` usage example Build arguments are commonly used to specify versions of components, such as image variants or package versions, used in a build. Specifying versions as build arguments lets you build with different versions without having to manually update the Dockerfile. It also makes it easier to maintain the Dockerfile, since it lets you declare versions at the top of the file. Build arguments can also be a way to reuse a value in multiple places. For example, if you use multiple flavors of `alpine` in your build, you can ensure you're using the same version of `alpine` everywhere: - `golang:1.22-alpine${ALPINE_VERSION}` - `python:3.12-alpine${ALPINE_VERSION}` - `nginx:1-alpine${ALPINE_VERSION}` The following example defines the version of `node` and `alpine` using build arguments. ```dockerfile # syntax=docker/dockerfile:1 ARG NODE_VERSION="{{% param example_node_version %}}" ARG ALPINE_VERSION="{{% param example_alpine_version %}}" FROM node:${NODE_VERSION}-alpine${ALPINE_VERSION} AS base WORKDIR /src FROM base AS build COPY package*.json ./ RUN npm ci RUN npm run build FROM base AS production COPY package*.json ./ RUN npm ci --omit=dev && npm cache clean --force COPY --from=build /src/dist/ .

Docker Build uses build arguments (ARG) and environment variables (ENV) to pass information into the build process, allowing for flexible and configurable builds. ARG is for parameterizing Dockerfile instructions, while ENV sets environment variables for the build execution environment and containers. ARG values can be set at build time, while ENV values must be declared in the Dockerfile. Both are unsuitable for secrets, and secret/SSH mounts should be used instead.