buildx/docs/reference/buildx_build.md

buildx build

docker buildx build [OPTIONS] PATH | URL | -

Start a build

Aliases

build, b

Options

Name	Description
--add-host stringSlice	Add a custom host-to-IP mapping (host:ip)
--allow stringSlice	Allow extra privileged entitlement, e.g. network.host, security.insecure
--build-arg stringArray	Set build-time variables
--builder string	Override the configured builder instance
--cache-from stringArray	External cache sources (eg. user/app:cache, type=local,src=path/to/dir)
--cache-to stringArray	Cache export destinations (eg. user/app:cache, type=local,dest=path/to/dir)
-f, --file string	Name of the Dockerfile (Default is 'PATH/Dockerfile')
--iidfile string	Write the image ID to the file
--label stringArray	Set metadata for an image
--load	Shorthand for --output=type=docker
--metadata-file string	Write build result metadata to the file
--network string	Set the networking mode for the RUN instructions during build
--no-cache	Do not use cache when building the image
-o, --output stringArray	Output destination (format: type=local,dest=path)
--platform stringArray	Set target platform for build
--progress string	Set type of progress output (auto, plain, tty). Use plain to show container output
--pull	Always attempt to pull a newer version of the image
--push	Shorthand for --output=type=registry
--secret stringArray	Secret file to expose to the build: id=mysecret,src=/local/secret
--ssh stringArray	SSH agent socket or keys to expose to the build (format: default
-t, --tag stringArray	Name and optionally a tag in the 'name:tag' format
--target string	Set the target build stage to build.

Description

The buildx build command starts a build using BuildKit. This command is similar to the UI of docker build command and takes the same flags and arguments.

For documentation on most of these flags, refer to the docker build documentation. In here we’ll document a subset of the new flags.

Examples

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

--platform=value[,value]

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 will be the current platform of the buildkit daemon.

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 RUN commands for your system architecture. If your kernel supports binfmt_misc launchers for secondary architectures, buildx will pick them up automatically. Docker desktop releases come with binfmt_misc automatically configured for arm64 and 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 through TARGETPLATFORM build argument. Please refer to the docker build documentation for the full description of automatic platform argument variants .

The formatting for the platform specifier is defined in the containerd source code.

Examples

$ docker buildx build --platform=linux/arm64 .
$ docker buildx build --platform=linux/amd64,linux/arm64,linux/arm/v7 .
$ docker buildx build --platform=darwin .

Set type of progress output (--progress)

--progress=VALUE

Set type of progress output (auto, plain, tty). Use plain to show container output (default "auto").

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

The following example uses plain output during the build:

$ docker buildx build --load --progress=plain .

#1 [internal] load build definition from Dockerfile
#1 transferring dockerfile: 227B 0.0s done
#1 DONE 0.1s

#2 [internal] load .dockerignore
#2 transferring context: 129B 0.0s done
#2 DONE 0.0s
...

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

-o, --output=[PATH,-,type=TYPE[,KEY=VALUE]

Sets the export action for the build result. In docker build all builds finish by creating a container image and exporting it to docker images. buildx makes this step configurable allowing results to be exported directly to the client, oci image tarballs, registry etc.

Buildx with docker driver currently only supports local, tarball exporter and image exporter. docker-container driver supports all the exporters.

If just the path is specified as a value, buildx will use the local exporter with this path as the destination. If the value is "-", buildx will use tar exporter and write to stdout.

Examples

$ docker buildx build -o . .
$ docker buildx build -o outdir .
$ docker buildx build -o - - > out.tar
$ docker buildx build -o type=docker .
$ docker buildx build -o type=docker,dest=- . > myimage.tar
$ docker buildx build -t tonistiigi/foo -o type=registry

Supported exported types are:

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

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.

oci

The oci export type writes the result image or manifest list as an OCI image layout tarball on the client.

Attribute key:

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

docker

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

Currently, multi-platform images cannot be exported with the docker export type. The most common usecase for multi-platform images is to directly push to a registry (see registry).

Attribute keys:

• dest - destination path where tarball will be written. If not specified the tar will be loaded automatically to the current docker instance.
• context - name for the docker context where to import the result

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.

registry

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

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

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

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.

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

--cache-from=[NAME|type=TYPE[,KEY=VALUE]]

Use an external cache source for a build. Supported types are registry and local. The registry source can import cache from a cache manifest or (special) image configuration on the registry. The local source can import cache from local files previously exported with --cache-to.

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

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

Examples

$ docker buildx build --cache-from=user/app:cache .
$ docker buildx build --cache-from=user/app .
$ docker buildx build --cache-from=type=registry,ref=user/app .
$ docker buildx build --cache-from=type=local,src=path/to/cache .

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

--cache-to=[NAME|type=TYPE[,KEY=VALUE]]

Export build cache to an external cache destination. Supported types are registry, local and inline. Registry exports build cache to a cache manifest in the registry, local exports cache to a local directory on the client and inline writes the cache metadata into the image configuration.

docker driver currently only supports exporting inline cache metadata to image configuration. Alternatively, --build-arg BUILDKIT_INLINE_CACHE=1 can be used to trigger inline cache exporter.

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.

Examples

$ docker buildx build --cache-to=user/app:cache .
$ docker buildx build --cache-to=type=inline .
$ docker buildx build --cache-to=type=registry,ref=user/app .
$ docker buildx build --cache-to=type=local,dest=path/to/cache .

Allow extra privileged entitlement (--allow)

--allow=ENTITLEMENT

Allow extra privileged entitlement. List of entitlements:

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

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

Examples

$ docker buildx create --use --name insecure-builder --buildkitd-flags '--allow-insecure-entitlement security.insecure'
$ docker buildx build --allow security.insecure .