Variables (original) (raw)

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.

SeeBuild secrets for more information.

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, seeARG 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, seeENV 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.

In this case, the build arguments have default values. Specifying their values when you invoke a build is optional. To override the defaults, you would use the --build-arg CLI flag:

For more information on how to use build arguments, refer to:

• ARG Dockerfile reference
• docker build --build-arg reference

Declaring an environment variable with ENV makes the variable available to all subsequent instructions in the build stage. The following example shows an example setting NODE_ENV to productionbefore installing JavaScript dependencies with npm. Setting the variable makes npm omits packages needed only for local development.

Environment variables aren't configurable at build-time by default. If you want to change the value of an ENV at build-time, you can combine environment variables and build arguments:

With this Dockerfile, you can use --build-arg to override the default value of NODE_ENV:

Note that, because the environment variables you set persist in containers, using them can lead to unintended side-effects for the application's runtime.

For more information on how to use environment variables in builds, refer to:

• ENV Dockerfile reference

Build arguments declared in the global scope of a Dockerfile aren't automatically inherited into the build stages. They're only accessible in the global scope.

The echo command in this example evaluates to hello !because the value of the NAME build argument is out of scope. To inherit global build arguments into a stage, you must consume them:

Once a build argument is declared or consumed in a stage, it's automatically inherited by child stages.

The following diagram further exemplifies how build argument and environment variable inheritance works for multi-stage builds.

This section describes pre-defined build arguments available to all builds by default.

Multi-platform build arguments

Multi-platform build arguments describe the build and target platforms for the build.

The build platform is the operating system, architecture, and platform variant of the host system where the builder (the BuildKit daemon) is running.

• BUILDPLATFORM
• BUILDOS
• BUILDARCH
• BUILDVARIANT

The target platform arguments hold the same values for the target platforms for the build, specified using the --platform flag for the docker build command.

• TARGETPLATFORM
• TARGETOS
• TARGETARCH
• TARGETVARIANT

These arguments are useful for doing cross-compilation in multi-platform builds. They're available in the global scope of the Dockerfile, but they aren't automatically inherited by build stages. To use them inside stage, you must declare them:

For more information about multi-platform build arguments, refer toMulti-platform arguments

Proxy arguments

Proxy build arguments let you specify proxies to use for your build. You don't need to declare or reference these arguments in the Dockerfile. Specifying a proxy with --build-arg is enough to make your build use the proxy.

Proxy arguments are automatically excluded from the build cache and the output of docker history by default. If you do reference the arguments in your Dockerfile, the proxy configuration ends up in the build cache.

The builder respects the following proxy build arguments. The variables are case insensitive.

• HTTP_PROXY
• HTTPS_PROXY
• FTP_PROXY
• NO_PROXY
• ALL_PROXY

To configure a proxy for your build:

For more information about proxy build arguments, refer toProxy arguments.

The following environment variables enable, disable, or change the behavior of Buildx and BuildKit. Note that these variables aren't used to configure the build container; they aren't available inside the build and they have no relation to the ENV instruction. They're used to configure the Buildx client, or the BuildKit daemon.

BuildKit also supports a few additional configuration parameters. Refer toBuildKit built-in build args.

You can express Boolean values for environment variables in different ways. For example, true, 1, and T all evaluate to true. Evaluation is done using the strconv.ParseBool function in the Go standard library. See thereference documentation for details.

BUILDKIT_COLORS

Changes the colors of the terminal output. Set BUILDKIT_COLORS to a CSV string in the following format:

Color values can be any valid RGB hex code, or one of theBuildKit predefined colors.

Setting NO_COLOR to anything turns off colorized output, as recommended byno-color.org.

BUILDKIT_HOST

Requires: Docker Buildx0.9.0 and later

You use the BUILDKIT_HOST to specify the address of a BuildKit daemon to use as a remote builder. This is the same as specifying the address as a positional argument to docker buildx create.

Usage:

If you specify both the BUILDKIT_HOST environment variable and a positional argument, the argument takes priority.

BUILDKIT_PROGRESS

Sets the type of the BuildKit progress output. Valid values are:

• auto (default)
• plain
• tty
• quiet
• rawjson

Usage:

BUILDKIT_TTY_LOG_LINES

You can change how many log lines are visible for active steps in TTY mode by setting BUILDKIT_TTY_LOG_LINES to a number (default to 6).

EXPERIMENTAL_BUILDKIT_SOURCE_POLICY

Lets you specify aBuildKit source policyfile for creating reproducible builds with pinned dependencies.

Example:

Requires: Docker Buildx0.14.0 and later

Sets the HTTP authentication scheme when using a remote Bake definition in a private Git repository. This is equivalent to theGIT_AUTH_HEADER secret, but facilitates the pre-flight authentication in Bake when loading the remote Bake file. Supported values are bearer (default) and basic.

Usage:

BUILDX_BAKE_GIT_AUTH_TOKEN

Requires: Docker Buildx0.14.0 and later

Sets the HTTP authentication token when using a remote Bake definition in a private Git repository. This is equivalent to theGIT_AUTH_TOKEN secret, but facilitates the pre-flight authentication in Bake when loading the remote Bake file.

Usage:

BUILDX_BAKE_GIT_SSH

Requires: Docker Buildx0.14.0 and later

Lets you specify a list of SSH agent socket filepaths to forward to Bake for authenticating to a Git server when using a remote Bake definition in a private repository. This is similar to SSH mounts for builds, but facilitates the pre-flight authentication in Bake when resolving the build definition.

Setting this environment is typically not necessary, because Bake will use the SSH_AUTH_SOCK agent socket by default. You only need to specify this variable if you want to use a socket with a different filepath. This variable can take multiple paths using a comma-separated string.

Usage:

BUILDX_BUILDER

Overrides the configured builder instance. Same as the docker buildx --builderCLI flag.

Usage:

BUILDX_CONFIG

You can use BUILDX_CONFIG to specify the directory to use for build configuration, state, and logs. The lookup order for this directory is as follows:

• $BUILDX_CONFIG
• $DOCKER_CONFIG/buildx
• ~/.docker/buildx (default)

Usage:

BUILDX_CPU_PROFILE

Requires: Docker Buildx0.18.0 and later

If specified, Buildx generates a pprof CPU profile at the specified location.

Note

This property is only useful for when developing Buildx. The profiling data is not relevant for analyzing a build's performance.

Usage:

BUILDX_EXPERIMENTAL

Enables experimental build features.

Usage:

BUILDX_GIT_CHECK_DIRTY

Requires: Docker Buildx0.10.4 and later

When set to true, checks for dirty state in source control information forprovenance attestations.

Usage:

BUILDX_GIT_INFO

Requires: Docker Buildx0.10.0 and later

When set to false, removes source control information fromprovenance attestations.

Usage:

BUILDX_GIT_LABELS

Requires: Docker Buildx0.10.0 and later

Adds provenance labels, based on Git information, to images that you build. The labels are:

• com.docker.image.source.entrypoint: Location of the Dockerfile relative to the project root
• org.opencontainers.image.revision: Git commit revision
• org.opencontainers.image.source: SSH or HTTPS address of the repository

Example:

Usage:

• Set BUILDX_GIT_LABELS=1 to include the entrypoint and revision labels.
• Set BUILDX_GIT_LABELS=full to include all labels.

If the repository is in a dirty state, the revision gets a -dirty suffix.

BUILDX_MEM_PROFILE

Requires: Docker Buildx0.18.0 and later

If specified, Buildx generates a pprof memory profile at the specified location.

Note

This property is only useful for when developing Buildx. The profiling data is not relevant for analyzing a build's performance.

Usage:

BUILDX_METADATA_PROVENANCE

Requires: Docker Buildx0.14.0 and later

By default, Buildx includes minimal provenance information in the metadata file through--metadata-file flag. This environment variable allows you to customize the provenance information included in the metadata file:

• min sets minimal provenance (default).
• max sets full provenance.
• disabled, false or 0 does not set any provenance.

BUILDX_METADATA_WARNINGS

Requires: Docker Buildx0.16.0 and later

By default, Buildx does not include build warnings in the metadata file through--metadata-file flag. You can set this environment variable to 1 or true to include them.

BUILDX_NO_DEFAULT_ATTESTATIONS

Requires: Docker Buildx0.10.4 and later

By default, BuildKit v0.11 and later addsprovenance attestations to images you build. Set BUILDX_NO_DEFAULT_ATTESTATIONS=1 to disable the default provenance attestations.

Usage:

BUILDX_NO_DEFAULT_LOAD

When you build an image using the docker driver, the image is automatically loaded to the image store when the build finishes. Set BUILDX_NO_DEFAULT_LOADto disable automatic loading of images to the local container store.

Usage: