DOCKER-BUILDX-BUILD(1)

📦 version 0.13.1, in debian trixie

✨ NAME ✨

okay so bestie, welcome to docker-buildx-build(1) — this whole page is about one single iconic thing and it's called Start a build 💖 periodt.

🦋 SYNOPSIS 🦋

docker buildx build [OPTIONS] PATH | URL | -

🌸 DESCRIPTION 🌸

so the buildx build command starts a build using BuildKit ✨. It's basically the same vibe as the UI of the docker build command, and it takes the same flags and arguments — no cap.

for the docs on most of these flags, go peek at ⟨/reference/cli/docker/image/build/⟩. this page is only describing a subset of the new flags, so don't come for me if your fave old flag isn't detailed here 🙈.

💅 OPTIONS 💅

here's the full roster, bestie. every single one. obsessed.

  • --add-host=[] — add a custom host-to-IP mapping (format: "host:ip") 🫶
  • --allow=[] — allow extra privileged entitlement (e.g., "network.host", "security.insecure")
  • --annotation=[] — add annotation to the image 🎀
  • --attest=[] — attestation parameters (format: "type=sbom,generator=image")
  • --build-arg=[] — set build-time variables
  • --build-context=[] — additional build contexts (e.g., name=path) ✨
  • --cache-from=[] — external cache sources (e.g., "user/app:cache", "type=local,src=path/to/dir")
  • --cache-to=[] — cache export destinations (e.g., "user/app:cache", "type=local,dest=path/to/dir")
  • --cgroup-parent="" — set the parent cgroup for the "RUN" instructions during build
  • -f, --file="" — name of the Dockerfile (default: "PATH/Dockerfile") 🦋
  • -h, --help[=false] — help for build
  • --iidfile="" — write the image ID to the file
  • --label=[] — set metadata for an image
  • --load[=false] — shorthand for "--output=type=docker"
  • --metadata-file="" — write build result metadata to the file
  • --network="default" — set the networking mode for the "RUN" instructions during build
  • --no-cache[=false] — do not use cache when building the image 💀
  • --no-cache-filter=[] — do not cache specified stages
  • -o, --output=[] — output destination (format: "type=local,dest=path")
  • --platform=[] — set target platform for build
  • --progress="auto" — set type of progress output ("auto", "plain", "tty"). use plain to show container output
  • --provenance="" — shorthand for "--attest=type=provenance"
  • --pull[=false] — always attempt to pull all referenced images
  • --push[=false] — shorthand for "--output=type=registry"
  • -q, --quiet[=false] — suppress the build output and print image ID on success 🤫
  • --sbom="" — shorthand for "--attest=type=sbom"
  • --secret=[] — secret to expose to the build (format: "id=mysecret[,src=/local/secret]")
  • --shm-size=0 — shared memory size for build containers
  • --ssh=[] — SSH agent socket or keys to expose to the build (format: "default|[=|[,]]")
  • -t, --tag=[] — name and optionally a tag (format: "name:tag") 👑
  • --target="" — set the target build stage to build
  • --ulimit=[] — ulimit options

🌈 OPTIONS INHERITED FROM PARENT COMMANDS 🌈

  • --builder="" — override the configured builder instance

🔥 EXAMPLE 🔥

Create annotations (--annotation) {#annotation}

--annotation="key=value"
--annotation="[type:]key=value"

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

$ docker buildx build -t TAG --annotation "foo=bar" --push .

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 the foo=bar annotation the image index instead of the manifests:

$ docker buildx build -t TAG --annotation "index:foo=bar" --push .

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

$ docker buildx build -t TAG --annotation "index,manifest,manifest-descriptor:foo=bar" --push .

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:

$ docker buildx build -t TAG --annotation "manifest[linux/amd64]:foo=bar" --push .
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 has linux as the OS platform.

for more information about annotations, see Annotations ⟨/build/building/annotations/⟩.

Create attestations (--attest) {#attest}

--attest=type=sbom,...
--attest=type=provenance,...

create image attestations ⟨/build/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⟩.

for more information, see here ⟨/build/attestations/sbom/⟩.

  • provenance — SLSA Provenance

use --attest=type=provenance to generate provenance for an image at build-time 💖. alternatively, you can use the ⟨#provenance⟩.

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, see here ⟨/build/attestations/slsa-provenance/⟩.

Allow extra privileged entitlement (--allow) {#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 ⟨/reference/dockerfile/#run---security⟩.

for entitlements to be enabled, the BuildKit daemon also needs to allow them with --allow-insecure-entitlement (see ⟨/reference/cli/docker/buildx/create/#buildkitd-flags⟩).

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

Set build-time variables (--build-arg) {#build-arg}

same as ⟨/reference/cli/docker/image/build/#build-arg⟩.

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 🫶
$ docker buildx build --build-arg BUILDKIT_MULTI_PLATFORM=1 .

learn more about the built-in build arguments in the Dockerfile reference docs ⟨/reference/dockerfile/#buildkit-built-in-build-args⟩.

Additional build contexts (--build-context) {#build-context}

--build-context=name=VALUE

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 ⟨https://github.com/opencontainers/image-spec/blob/main/image-layout.md⟩, container image (with docker-image:// prefix), Git or HTTP URL.

replace alpine:latest with a pinned one:

$ docker buildx build --build-context alpine=docker-image://alpine@sha256:0123456789 .

expose a secondary local source directory:

$ docker buildx build --build-context project=path/to/project/source .
# docker buildx build --build-context project=https://github.com/myuser/project.git .
# syntax=docker/dockerfile:1
FROM alpine
COPY --from=project myfile /

Use an OCI layout directory as build context {#source-oci-layout}

source an image from a local OCI layout compliant directory ⟨https://github.com/opencontainers/image-spec/blob/main/image-layout.md⟩, either by tag, or by digest:

$ docker buildx build --build-context foo=oci-layout:///path/to/local/layout:<tag>
$ docker buildx build --build-context foo=oci-layout:///path/to/local/layout@sha256:<digest>
# syntax=docker/dockerfile:1
FROM alpine
RUN apk add git
COPY --from=foo myfile /

FROM foo

the OCI layout directory must be compliant with the OCI layout specification ⟨https://github.com/opencontainers/image-spec/blob/main/image-layout.md⟩ 🙏. you can reference an image in the layout using either tags, or the exact digest.

Override the configured builder instance (--builder) {#builder}

same as ⟨/reference/cli/docker/buildx/#builder⟩.

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

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

use an external cache source for a build 🔥. supported types are registry, local, gha and s3.

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

docker driver currently only supports importing build cache from the registry 💀.
$ 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 .
$ docker buildx build --cache-from=type=gha .
$ docker buildx build --cache-from=type=s3,region=eu-west-1,bucket=mybucket .

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

Export build cache to an external cache destination (--cache-to) {#cache-to}

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

export build cache to an external cache destination 🌈. supported types are registry, local, inline, gha and s3.

…and bestie, the --cache-to list is not done yet, there's two more backends:

The docker driver only supports cache exports using the inline and local cache backends. That's the whole vibe, no cap.

Attribute key:

  • mode — tells the build how many layers get exported with the cache. min only exports layers that are already in the final build stage, max exports layers for all stages. Metadata is always exported for the whole build, no matter what.
$ 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 .
$ docker buildx build --cache-to=type=gha .
$ docker buildx build --cache-to=type=s3,region=eu-west-1,bucket=mybucket .

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

🫶 Load the single-platform build result to docker images (--load) 🫶 {#load}

Shorthand for #docker. It'll automatically load the single-platform build result into docker images for you. easy, breezy, iconic.

🎀 Write build result metadata to the file (--metadata-file) 🎀 {#metadata-file}

Wanna get the build metadata out — stuff like the image digest? Pass the --metadata-file flag, babe. The metadata gets written as a JSON object into the file you point at. Important: the directory of that file has to already exist and be writable, or it's giving nothing.

$ docker buildx build --load --metadata-file metadata.json .
$ cat metadata.json
{
  "buildx.build.ref": "mybuilder/mybuilder0/0fjb6ubs52xx3vygf6fgdl611",
  "containerimage.config.digest": "sha256:2937f66a9722f7f4a2df583de2f8cb97fc9196059a410e7f00072fc918930e66",
  "containerimage.descriptor": {
    "annotations": {
      "config.digest": "sha256:2937f66a9722f7f4a2df583de2f8cb97fc9196059a410e7f00072fc918930e66",
      "org.opencontainers.image.created": "2022-02-08T21:28:03Z"
    },
    "digest": "sha256:19ffeab6f8bc9293ac2c3fdf94ebe28396254c993aea0b5a542cfb02e0883fa3",
    "mediaType": "application/vnd.oci.image.manifest.v1+json",
    "size": 506
  },
  "containerimage.digest": "sha256:19ffeab6f8bc9293ac2c3fdf94ebe28396254c993aea0b5a542cfb02e0883fa3"
}

💀 Ignore build cache for specific stages (--no-cache-filter) 💀 {#no-cache-filter}

The --no-cache-filter lets you name one or more stages of a multi-stage Dockerfile where the build cache should just be ignored. Wanna do several stages at once? Comma-separated syntax, bestie:

$ docker buildx build --no-cache-filter stage1,stage2,stage3 .

For example, this Dockerfile right here has four stages:

  • base
  • install
  • test
  • release
# syntax=docker/dockerfile:1

FROM oven/bun:1 as base
WORKDIR /app

FROM base AS install
WORKDIR /temp/dev
RUN --mount=type=bind,source=package.json,target=package.json \
    --mount=type=bind,source=bun.lockb,target=bun.lockb \
    bun install --frozen-lockfile

FROM base AS test
COPY --from=install /temp/dev/node_modules node_modules
COPY . .
RUN bun test

FROM base AS release
ENV NODE_ENV=production
COPY --from=install /temp/dev/node_modules node_modules
COPY . .
ENTRYPOINT ["bun", "run", "index.js"]

To ignore the cache for the install stage:

$ docker buildx build --no-cache-filter install .

To ignore the cache for the install and release stages:

$ docker buildx build --no-cache-filter install,release .

The arguments for the --no-cache-filter flag must be names of stages. that's the rule, periodt.

✨ Set the export action for the build result (-o, --output) ✨ {#output}

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

This one sets the export action for the build result. In docker build, literally every build finishes by creating a container image and exporting it to docker images — that's the only option. buildx said "no thank you" and made this step configurable, so results can be exported straight to the client, to OCI image tarballs, to a registry, etc. obsessed with the flexibility tbh.

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

If you pass just a path as the value, buildx uses the local exporter with that path as the destination. If the value is -, buildx uses the tar exporter and writes to stdout. 🌈

$ 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
Note 📌 Since BuildKit v0.13.0 you can specify multiple outputs by repeating the flag. stack them, bestie.

Supported exported types are:

🌸 local

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

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 get put in subdirectories by their platform.

Attribute key:

  • dest — destination path where the 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. The layout spec lives at https://github.com/opencontainers/image-spec/blob/v1.0.1/image-layout.md.

Attribute key:

  • dest — destination path where the 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 — spec at https://github.com/docker/docker/blob/v20.10.2/image/spec/v1.2.md. Tarballs created by this exporter are also OCI compatible, which is lowkey iconic.

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 by directly pushing to a registry instead — see #registry.

Attribute keys:

  • dest — destination path where the tarball will be written. If you don't specify it, the tar will be loaded automatically to the local image store.
  • 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 you're using the docker driver, the image will show up 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. that's the whole thing, she's simple like that.

🌈 Set the target platforms for the build (--platform) 🌈 {#platform}

--platform=value[,value]

Sets the target platform for the build. Every FROM command inside the Dockerfile that doesn't have its own --platform flag will pull base images for this platform, and this value is also gonna 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 — like linux/amd64 or linux/arm/v7. Plus, the --platform flag also supports a special local value, which tells BuildKit to use the platform of the BuildKit client that invoked the build. cute.

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

If your 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 https://en.wikipedia.org/wiki/Binfmt_misc launchers for secondary architectures, buildx will pick them up automatically. Docker desktop releases come with binfmt_misc already configured for arm64 and arm architectures. Wanna see what runtime platforms your current builder instance supports? Run docker buildx inspect --bootstrap.

Inside a Dockerfile, you can access the current platform value through the TARGETPLATFORM build argument. The full description of automatic platform argument variants is at /reference/dockerfile/#automatic-platform-args-in-the-global-scope.

You can find the formatting definition for the platform specifier in the containerd source code at https://github.com/containerd/containerd/blob/v1.4.3/platforms/platforms.go#L63.

$ 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}

--progress=VALUE

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

Note 📌 You can also use the BUILDKIT_PROGRESS environment variable to set its value. env var girlies stay winning.

This 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
...
Note 📌 Check also our Color output controls guide at https://github.com/docker/buildx/blob/master/docs/guides/color-output.md for modifying the colors that get used to output information to the terminal. aesthetic matters.

💖 Create provenance attestations (--provenance) 💖 {#provenance}

Shorthand for #attest, 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.

Also, --provenance can be used with Boolean values to enable or disable provenance attestations. Like, --provenance=false disables all provenance attestations, while --provenance=true enables all provenance attestations. simple as that bestie 🫶

By default, a minimal provenance attestation gets created for the build result. 💖 Big note though: the default image store in Docker Engine doesn't support attestations, periodt. 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. ✨

Want the full lore on provenance attestations? See /build/attestations/slsa-provenance/.

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

Shorthand for #registry. It will automatically push the build result to registry. no cap, that's the whole thing 🫶

🎀 Create SBOM attestations (--sbom)

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

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, see /build/attestations/sbom/.

🦋 Secret to expose to the build (--secret)

--secret=[type=TYPE[,KEY=VALUE]

Exposes secret to the build. The secret can be used by the build using /reference/dockerfile/#run---mounttypesecret.

If type is unset it will be detected. Supported types are:

file

Attribute keys:

  • id - ID of the secret. Defaults to base name of the src path.
  • src, source - Secret filename. id used if unset.
# syntax=docker/dockerfile:1
FROM python:3
RUN pip install awscli
RUN --mount=type=secret,id=aws,target=/root/.aws/credentials \
  aws s3 cp s3://... ...
$ docker buildx build --secret id=aws,src=$HOME/.aws/credentials .

env

Attribute keys:

  • id - ID of the secret. Defaults to env name.
  • env - Secret environment variable. id used if unset, otherwise will look for src, source if id unset.
# syntax=docker/dockerfile:1
FROM node:alpine
RUN --mount=type=bind,target=. \
  --mount=type=secret,id=SECRET_TOKEN \
  SECRET_TOKEN=$(cat /run/secrets/SECRET_TOKEN) yarn run test
$ SECRET_TOKEN=token docker buildx build --secret id=SECRET_TOKEN .

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

Sets the size of the shared memory allocated for build containers when using RUN 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)

--ssh=default|<id>[=<socket>|<key>[,<key>]]

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 the /reference/dockerfile/#run---mounttypessh.

Example to access Gitlab using an SSH agent socket:

# syntax=docker/dockerfile:1
FROM alpine
RUN apk add --no-cache openssh-client
RUN mkdir -p -m 0700 ~/.ssh && ssh-keyscan gitlab.com >> ~/.ssh/known_hosts
RUN --mount=type=ssh ssh -q -T git@gitlab.com 2>&1 | tee /hello
# "Welcome to GitLab, @GITLAB_USERNAME_ASSOCIATED_WITH_SSHKEY" should be printed here
# with the type of build progress is defined as `plain`.
$ eval $(ssh-agent)
$ ssh-add ~/.ssh/id_rsa
(Input your passphrase here)
$ docker buildx build --ssh default=$SSH_AUTH_SOCK .

👑 Set ulimits (--ulimit)

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

$ docker buildx build --ulimit nofile=1024:1024 .
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.

🔥 SEE ALSO 🔥

okay bestie that's the whole page, you made it, main character energy fr fr 💖 This one's from the Apr 2025 era and it's the DOCKER-BUILDX-BUILD(1) page — go forth and build, slay, etc. 💅✨

📦 where this page comes from