docker buildx build (original) (raw)

The docker buildx build command starts a build using BuildKit.

Add entries to container hosts file (--add-host)

You can add other hosts into a build container's /etc/hosts file by using one or more --add-host flags. This example adds static addresses for hosts namedmy-hostname and my_hostname_v6:

If you need your build to connect to services running on the host, you can use the special host-gateway value for --add-host. In the following example, build containers resolve host.docker.internal to the host's gateway IP.

You can wrap an IPv6 address in square brackets.= and : are both valid separators. Both formats in the following example are valid:

Create annotations (--annotation)

Add OCI annotations to the image index, manifest, or descriptor. The following example adds the foo=bar annotation to the image manifests:

You can optionally add a type prefix to specify the level of the annotation. By default, the image manifest is annotated. The following example adds thefoo=bar annotation the image index instead of the manifests:

You can specify multiple types, separated by a comma (,) to add the annotation to multiple image components. The following example adds the foo=barannotation to image index, descriptors, manifests:

You can also specify a platform qualifier in square brackets ([os/arch]) in the type prefix, to apply the annotation to a subset of manifests with the matching platform. The following example adds the foo=bar annotation only to the manifest with the linux/amd64 platform:

Wildcards are not supported in the platform qualifier; you can't specify a type prefix like manifest[linux/*] to add annotations only to manifests which haslinux as the OS platform.

For more information about annotations, seeAnnotations.

Create attestations (--attest)

Createimage attestations. BuildKit currently supports:

• sbom - Software Bill of Materials.
  Use --attest=type=sbom to generate an SBOM for an image at build-time. Alternatively, you can use the--sbom shorthand.
  For more information, seehere.
• provenance - SLSA Provenance
  Use --attest=type=provenance to generate provenance for an image at build-time. Alternatively, you can use the--provenance shorthand.
  By default, a minimal provenance attestation will be created for the build result, which will only be attached for images pushed to registries.
  For more information, seehere.

Allow extra privileged entitlement (--allow)

Allow extra privileged entitlement. List of entitlements:

• network.host - Allows executions with host networking.
• security.insecure - Allows executions without sandbox. Seerelated Dockerfile extensions.

For entitlements to be enabled, the BuildKit daemon also needs to allow them with --allow-insecure-entitlement (seecreate --buildkitd-flags).

Set build-time variables (--build-arg)

You can use ENV instructions in a Dockerfile to define variable values. These values persist in the built image. Often persistence isn't what you want. Users want to specify variables differently depending on which host they build an image on.

A good example is http_proxy or source versions for pulling intermediate files. The ARG instruction lets Dockerfile authors define values that users can set at build-time using the --build-arg flag:

This flag allows you to pass the build-time variables that are accessed like regular environment variables in the RUN instruction of the Dockerfile. These values don't persist in the intermediate or final images like ENV values do. You must add --build-arg for each build argument.

Using this flag doesn't alter the output you see when the build process echoes theARG lines from the Dockerfile.

For detailed information on using ARG and ENV instructions, see theDockerfile reference.

You can also use the --build-arg flag without a value, in which case the daemon propagates the value from the local environment into the Docker container it's building:

This example is similar to how docker run -e works. Refer to thedocker run documentationfor more information.

There are also useful built-in build arguments, such as:

• BUILDKIT_CONTEXT_KEEP_GIT_DIR=<bool>: trigger git context to keep the .git directory
• BUILDKIT_INLINE_CACHE=<bool>: inline cache metadata to image config or not
• BUILDKIT_MULTI_PLATFORM=<bool>: opt into deterministic output regardless of multi-platform output or not

Learn more about the built-in build arguments in theDockerfile reference docs.

Additional build contexts (--build-context)

Define additional build context with specified contents. In Dockerfile the context can be accessed when FROM name or --from=name is used. When Dockerfile defines a stage with the same name it is overwritten.

The value can be a local source directory,local OCI layout compliant directory, container image (with docker-image:// prefix), Git or HTTP URL.

Replace alpine:latest with a pinned one:

Expose a secondary local source directory:

Use an OCI layout directory as build context

Source an image from a localOCI layout compliant directory, either by tag, or by digest:

The OCI layout directory must be compliant with theOCI layout specification. You can reference an image in the layout using either tags, or the exact digest.

Override the configured builder instance (--builder)

Same asbuildx --builder.

Use an external cache source for a build (--cache-from)

Use an external cache source for a build. Supported types are registry,local, gha and s3.

• registry sourcecan import cache from a cache manifest or (special) image configuration on the registry.
• local source can import cache from local files previously exported with --cache-to.
• gha sourcecan import cache from a previously exported cache with --cache-to in your GitHub repository
• s3 sourcecan import cache from a previously exported cache with --cache-to in your S3 bucket

If no type is specified, registry exporter is used with a specified reference.

docker driver currently only supports importing build cache from the registry.

More info about cache exporters and available attributes:https://github.com/moby/buildkit#export-cache

Invoke a frontend method (--call)

BuildKit frontends can support alternative modes of executions for builds, using frontend methods. Frontend methods are a way to change or extend the behavior of a build invocation, which lets you, for example, inspect, validate, or generate alternative outputs from a build.

The --call flag for docker buildx build lets you specify the frontend method that you want to execute. If this flag is unspecified, it defaults to executing the build and evaluatingbuild checks.

For Dockerfiles, the available methods are:

Note that other frontends may implement these or other methods. To see the list of available methods for the frontend you're using, use --call=subrequests.describe.

Descriptions

The--call=targets and--call=outlinemethods include descriptions for build targets and arguments, if available. Descriptions are generated from comments in the Dockerfile. A comment on the line before a FROM instruction becomes the description of a build target, and a comment before an ARG instruction the description of a build argument. The comment must lead with the name of the stage or argument, for example:

When you run docker buildx build --call=outline, the output includes the descriptions, as follows:

For more examples on how to write Dockerfile docstrings, check outthe Dockerfile for Docker docs.

Call: check (--check)

The check method evaluates build checks without executing the build. The--check flag is a convenient shorthand for --call=check. Use the checkmethod to validate the build configuration before starting the build.

Using --check without specifying a target evaluates the entire Dockerfile. If you want to evaluate a specific target, use the --target flag.

Call: outline

The outline method prints the name of the specified target (or the default target, if --target isn't specified), and the build arguments that the target consumes, along with their default values, if set.

The following example shows the default target release and its build arguments:

This means that the release target is configurable using these build arguments:

Call: targets

The targets method lists all the build targets in the Dockerfile. These are the stages that you can build using the --target flag. It also indicates the default target, which is the target that will be built when you don't specify a target.

Export build cache to an external cache destination (--cache-to)

Export build cache to an external cache destination. Supported types areregistry, local, inline, gha and s3.

• registry type exports build cache to a cache manifest in the registry.
• local type exports cache to a local directory on the client.
• inline typewrites the cache metadata into the image configuration.
• gha typeexports cache through theGitHub Actions Cache service API.
• s3 type exports cache to a S3 bucket.

The docker driver only supports cache exports using the inline and localcache backends.

Attribute key:

• mode - Specifies how many layers are exported with the cache. min on only exports layers already in the final build stage, max exports layers for all stages. Metadata is always exported for the whole build.

More info about cache exporters and available attributes:https://github.com/moby/buildkit#export-cache

Use a custom parent cgroup (--cgroup-parent)

When you run docker buildx build with the --cgroup-parent option, the daemon runs the containers used in the build with thecorresponding docker run flag.

Specify a Dockerfile (-f, --file)

Specifies the filepath of the Dockerfile to use. If unspecified, a file named Dockerfile at the root of the build context is used by default.

To read a Dockerfile from stdin, you can use - as the argument for --file.

Load the single-platform build result to docker images (--load)

Shorthand for--output=type=docker. Will automatically load the single-platform build result to docker images.

Write build result metadata to a file (--metadata-file)

To output build metadata such as the image digest, pass the --metadata-file flag. The metadata will be written as a JSON object to the specified file. The directory of the specified file must already exist and be writable.

Note

Build recordprovenance(buildx.build.provenance) includes minimal provenance by default. Set theBUILDX_METADATA_PROVENANCE environment variable to customize this behavior:

• min sets minimal provenance (default).
• max sets full provenance.
• disabled, false or 0 doesn't set any provenance.

Note

Build warnings (buildx.build.warnings) are not included by default. Set theBUILDX_METADATA_WARNINGS environment variable to 1 or true to include them.

Set the networking mode for the RUN instructions during build (--network)

Available options for the networking mode are:

• default (default): Run in the default network.
• none: Run with no network access.
• host: Run in the host’s network environment.

Find more details in theDockerfile reference.

Ignore build cache for specific stages (--no-cache-filter)

The --no-cache-filter lets you specify one or more stages of a multi-stage Dockerfile for which build cache should be ignored. To specify multiple stages, use a comma-separated syntax:

For example, the following Dockerfile contains four stages:

• base
• install
• test
• release

To ignore the cache for the install stage:

To ignore the cache the install and release stages:

The arguments for the --no-cache-filter flag must be names of stages.

Set the export action for the build result (-o, --output)

Sets the export action for the build result. The default output, when using thedocker build driver, is a container image exported to the local image store. The --output flag makes this step configurable allows export of results directly to the client's filesystem, an OCI image tarball, a registry, and more.

Buildx with docker driver only supports the local, tarball, and imageexporters. The docker-containerdriver supports all exporters.

If you only specify a filepath as the argument to --output, Buildx uses the local exporter. If the value is -, Buildx uses the tar exporter and writes the output to stdout.

You can export multiple outputs by repeating the flag.

Supported exported types are:

• local
• tar
• oci
• docker
• image
• registry

local

The local export type writes all result files to a directory on the client. The new files will be owned by the current user. On multi-platform builds, all results will be put in subdirectories by their platform.

Attribute key:

• dest - destination directory where files will be written

For more information, seeLocal and tar exporters.

tar

The tar export type writes all result files as a single tarball on the client. On multi-platform builds all results will be put in subdirectories by their platform.

Attribute key:

• dest - destination path where tarball will be written. “-” writes to stdout.

For more information, seeLocal and tar exporters.

oci

The oci export type writes the result image or manifest list as anOCI image layouttarball on the client.

Attribute key:

• dest - destination path where tarball will be written. “-” writes to stdout.

For more information, seeOCI and Docker exporters.

docker

The docker export type writes the single-platform result image as aDocker image specificationtarball on the client. Tarballs created by this exporter are also OCI compatible.

The default image store in Docker Engine doesn't support loading multi-platform images. You can enable the containerd image store, or push multi-platform images is to directly push to a registry, seeregistry.

Attribute keys:

• dest - destination path where tarball will be written. If not specified, the tar will be loaded automatically to the local image store.
• context - name for the Docker context where to import the result

For more information, seeOCI and Docker exporters.

image

The image exporter writes the build result as an image or a manifest list. When using docker driver the image will appear in docker images. Optionally, image can be automatically pushed to a registry by specifying attributes.

Attribute keys:

• name - name (references) for the new image.
• push - Boolean to automatically push the image.

For more information, seeImage and registry exporters.

registry

The registry exporter is a shortcut for type=image,push=true.

For more information, seeImage and registry exporters.

Set the target platforms for the build (--platform)

Set the target platform for the build. All FROM commands inside the Dockerfile without their own --platform flag will pull base images for this platform and this value will also be the platform of the resulting image.

The default value is the platform of the BuildKit daemon where the build runs. The value takes the form of os/arch or os/arch/variant. For example,linux/amd64 or linux/arm/v7. Additionally, the --platform flag also supports a special local value, which tells BuildKit to use the platform of the BuildKit client that invokes the build.

When using docker-container driver with buildx, this flag can accept multiple values as an input separated by a comma. With multiple values the result will be built for all of the specified platforms and joined together into a single manifest list.

If the Dockerfile needs to invoke the RUN command, the builder needs runtime support for the specified platform. In a clean setup, you can only execute RUNcommands for your system architecture. If your kernel supportsbinfmt_misclaunchers for secondary architectures, buildx will pick them up automatically. Docker Desktop releases come with binfmt_misc automatically configured for arm64and arm architectures. You can see what runtime platforms your current builder instance supports by running docker buildx inspect --bootstrap.

Inside a Dockerfile, you can access the current platform value throughTARGETPLATFORM build argument. Refer to theDockerfile referencefor the full description of automatic platform argument variants .

You can find the formatting definition for the platform specifier in thecontainerd source code.

Set type of progress output (--progress)

Set type of progress output. Supported values are:

• auto (default): Uses the tty mode if the client is a TTY, or plain otherwise
• tty: An interactive stream of the output with color and redrawing
• plain: Prints the raw build progress in a plaintext format
• quiet: Suppress the build output and print image ID on success (same as --quiet)
• rawjson: Prints the raw build progress as JSON lines

Note

You can also use the BUILDKIT_PROGRESS environment variable to set its value.

The following example uses plain output during the build:

Note

Check also theBUILDKIT_COLORSenvironment variable for modifying the colors of the terminal output.

The rawjson output marshals the solve status events from BuildKit to JSON lines. This mode is designed to be read by an external program.

Create provenance attestations (--provenance)

Shorthand for--attest=type=provenance, used to configure provenance attestations for the build result. For example,--provenance=mode=max can be used as an abbreviation for--attest=type=provenance,mode=max.

Additionally, --provenance can be used with Boolean values to enable or disable provenance attestations. For example, --provenance=false disables all provenance attestations, while --provenance=true enables all provenance attestations.

By default, a minimal provenance attestation will be created for the build result. Note that the default image store in Docker Engine doesn't support attestations. Provenance attestations only persist for images pushed directly to a registry if you use the default image store. Alternatively, you can switch to using the containerd image store.

For more information about provenance attestations, seehere.

Push the build result to a registry (--push)

Shorthand for--output=type=registry. Will automatically push the build result to registry.

Create SBOM attestations (--sbom)

Shorthand for--attest=type=sbom, used to configure SBOM attestations for the build result. For example,--sbom=generator=<user>/<generator-image> can be used as an abbreviation for--attest=type=sbom,generator=<user>/<generator-image>.

Additionally, --sbom can be used with Boolean values to enable or disable SBOM attestations. For example, --sbom=false disables all SBOM attestations.

Note that the default image store in Docker Engine doesn't support attestations. Provenance attestations only persist for images pushed directly to a registry if you use the default image store. Alternatively, you can switch to using the containerd image store.

For more information, seehere.

Secret to expose to the build (--secret)

Exposes secrets (authentication credentials, tokens) to the build. A secret can be mounted into the build using a RUN --mount=type=secret mount in theDockerfile. For more information about how to use build secrets, seeBuild secrets.

Supported types are:

• type=file
• type=env

Buildx attempts to detect the type automatically if unset. If an environment variable with the same key as id is set, then Buildx uses type=env and the variable value becomes the secret. If no such environment variable is set, andtype is not set, then Buildx falls back to type=file.

type=file

Source a build secret from a file.

type=file synopsis

type=file attributes

type=file usage

In the following example, type=file is automatically detected because no environment variable matching aws (the ID) is set.

type=env

Source a build secret from an environment variable.

type=env synopsis

type=env attributes

type=env usage

In the following example, type=env is automatically detected because an environment variable matching id is set.

In the following example, the build argument SECRET_TOKEN is set to contain the value of the environment variable API_KEY.

You can also specify the name of the environment variable with src or source:

Note

Specifying the environment variable name with src or source, you are required to set type=env explicitly, or else Buildx assumes that the secret is type=file, and looks for a file with the name of src or source (in this case, a file named API_KEY relative to the location where the docker buildx build command was executed.

Shared memory size for build containers (--shm-size)

Sets the size of the shared memory allocated for build containers when usingRUN instructions.

The format is <number><unit>. number must be greater than 0. Unit is optional and can be b (bytes), k (kilobytes), m (megabytes), or g(gigabytes). If you omit the unit, the system uses bytes.

Note

In most cases, it is recommended to let the builder automatically determine the appropriate configurations. Manual adjustments should only be considered when specific performance tuning is required for complex build scenarios.

SSH agent socket or keys to expose to the build (--ssh)

This can be useful when some commands in your Dockerfile need specific SSH authentication (e.g., cloning a private repository).

--ssh exposes SSH agent socket or keys to the build and can be used with theRUN --mount=type=ssh mount.

Example to access Gitlab using an SSH agent socket:

Tag an image (-t, --tag)

This examples builds in the same way as the previous example, but it then tags the resulting image. The repository name will be docker/apache and the tag 2.0.

Read more about valid tags.

You can apply multiple tags to an image. For example, you can apply the latesttag to a newly built image and add another tag that references a specific version.

For example, to tag an image both as docker/fedora-jboss:latest anddocker/fedora-jboss:v2.1, use the following:

Specifying target build stage (--target)

When building a Dockerfile with multiple build stages, use the --targetoption to specify an intermediate build stage by name as a final stage for the resulting image. The builder skips commands after the target stage.

Set ulimits (--ulimit)

--ulimit overrides the default ulimits of build's containers when using RUNinstructions and are specified with a soft and hard limit as such:<type>=<soft limit>[:<hard limit>], for example:

Note

If you don't provide a hard limit, the soft limit is used for both values. If no ulimits are set, they're inherited from the default ulimits set on the daemon.

Note

In most cases, it is recommended to let the builder automatically determine the appropriate configurations. Manual adjustments should only be considered when specific performance tuning is required for complex build scenarios.