# docker buildx bake **Description:** Build from a file **Usage:** `docker buildx bake [OPTIONS] [TARGET...]` **Aliases:** `docker buildx f` ## Description Bake is a high-level build command. Each specified target runs in parallel as part of the build. Read [High-level build options with Bake](/build/bake/) guide for introduction to writing bake files. ## Options | Option | Default | Description | |--------|---------|-------------| | `--allow` | | Allow build to access specified resources | | `--call` | `build` | Set method for evaluating build (`check`, `outline`, `targets`) | | `--check` | | Shorthand for `--call=check` | | `-f`, `--file` | | Build definition file | | `-j`, `--jobs` | `fail-fast` | Set target execution behavior (format: `N` or `mode[,parallel=N]`) | | `--list` | | List targets or variables | | `--load` | | Shorthand for `--set=*.output=type=docker`. Conditional. | | `--metadata-file` | | Write build result metadata to a file | | `--no-cache` | | Do not use cache when building the image | | `--policy` | | Global policy evaluation options (format: `[disabled=true|false][,strict=true|false][,log-level=level]`)
| | `--print` | | Print the options without building | | `--progress` | `auto` | Set type of progress output (`auto`, `none`, `plain`, `quiet`, `rawjson`, `tty`). Use plain to show container output
| | `--provenance` | | Shorthand for `--set=*.attest=type=provenance` | | `--pull` | | Always attempt to pull all referenced images | | `--push` | | Shorthand for `--set=*.output=type=registry`. Conditional. | | `--sbom` | | Shorthand for `--set=*.attest=type=sbom` | | `--set` | | Override target value (e.g., `targetpattern.key=value`) | | `--var` | | Set a variable value (e.g., `name=value`) | ## Examples ### Allow extra privileged entitlement (--allow) {#allow} ```text --allow=ENTITLEMENT[=VALUE] ``` Entitlements are designed to provide controlled access to privileged operations. By default, Buildx and BuildKit operates with restricted permissions to protect users and their systems from unintended side effects or security risks. The `--allow` flag explicitly grants access to additional entitlements, making it clear when a build or bake operation requires elevated privileges. In addition to BuildKit's `network.host` and `security.insecure` entitlements (see [`docker buildx build --allow`](/reference/cli/docker/buildx/build/#allow)), Bake supports file system entitlements that grant granular control over file system access. These are particularly useful when working with builds that need access to files outside the default working directory. Bake supports the following filesystem entitlements: - `--allow fs=` - Grant read and write access to files outside of the working directory. - `--allow fs.read=` - Grant read access to files outside of the working directory. - `--allow fs.write=` - Grant write access to files outside of the working directory. The `fs` entitlements take a path value (relative or absolute) to a directory on the filesystem. Alternatively, you can pass a wildcard (`*`) to allow Bake to access the entire filesystem. Bake also supports `--allow=buildx.local.delete` to grant local outputs permission to delete stale files when `mode=delete` is set. ### Example: fs.read Given the following Bake configuration, Bake would need to access the parent directory, relative to the Bake file. ```hcl target "app" { context = "../src" } ``` Assuming `docker buildx bake app` is executed in the same directory as the `docker-bake.hcl` file, you would need to explicitly allow Bake to read from the `../src` directory. In this case, the following invocations all work: ```console $ docker buildx bake --allow fs.read=* app $ docker buildx bake --allow fs.read=../src app $ docker buildx bake --allow fs=* app ``` ### Example: fs.write The following `docker-bake.hcl` file requires write access to the `/tmp` directory. ```hcl target "app" { output = "/tmp" } ``` Assuming `docker buildx bake app` is executed outside of the `/tmp` directory, you would need to allow the `fs.write` entitlement, either by specifying the path or using a wildcard: ```console $ docker buildx bake --allow fs=/tmp app $ docker buildx bake --allow fs.write=/tmp app $ docker buildx bake --allow fs.write=* app ``` ### Override the configured builder instance (--builder) {#builder} Same as [`buildx --builder`](/reference/cli/docker/buildx/#builder). ### Invoke a frontend method (--call) {#call} Same as [`build --call`](/reference/cli/docker/buildx/build/#call). #### Call: check (--check) {#check} Same as [`build --check`](/reference/cli/docker/buildx/build/#check). ### Configure target execution behavior (--jobs, -j) {#jobs} ```text --jobs=N --jobs=[mode,]parallel=N --jobs=mode ``` The `--jobs` flag (shorthand `-j`) controls target concurrency, output synchronization, and how Bake handles target failures. It accepts an integer as shorthand for `parallel=N`, or comma-separated mode and parallel options. For example, `-j=2` is equivalent to `--jobs=parallel=2`, and `--jobs=defer-error,parallel=2` combines a mode with a concurrency limit. The mode can also be written as `mode=defer-error`. The default mode is `fail-fast`, which stops the build when a target fails and cancels targets that are still running. Outputs already written by successful targets are not removed. The `defer-output` mode waits until all participating targets have successfully evaluated their build results before any target begins exporting output. This is useful when multiple targets produce related artifacts and you want to withhold their outputs if a build fails. Exports are not transactional: an export failure can still leave partial output, and completed exports are not rolled back. For multi-node targets, `defer-output` applies to the BuildKit solve and export boundary for each target. Any manifest list merge or registry push that Buildx performs after the per-node solves complete is not part of this synchronization barrier. The `defer-error` mode allows independent targets to keep running after another target fails. Bake still returns an error after all possible targets complete, but successful targets can finish and write their outputs. Targets that depend on a failed target cannot complete successfully. When `--metadata-file` is set, Bake writes metadata for successful targets even if another target fails. ```console $ docker buildx bake --jobs=defer-output # wait for all build results before exporting $ docker buildx bake --jobs=defer-error # let independent targets finish before returning an error ``` The `parallel` option limits how many Bake targets run at the same time. It requires a non-negative integer. When omitted or set to `0`, Bake doesn't apply a target concurrency limit. This controls target scheduling, not BuildKit's internal parallelism for build steps within a target. Specify the mode and limit in the same flag value; repeating `--jobs` replaces the previous value. ```console $ docker buildx bake -j=2 # run at most two targets at the same time $ docker buildx bake --jobs=parallel=1 # run targets sequentially $ docker buildx bake --jobs=defer-error,parallel=2 # limit concurrency and let independent targets finish after a failure ``` With `defer-output`, every participating target must be able to reach the output boundary before any target completes. A nonzero jobs limit smaller than the number of participating targets is therefore rejected. The same restriction applies when linked targets are present, because their solves may need to be active together. The count includes implicit targets referenced through `target:` contexts. ### Specify a build definition file (-f, --file) {#file} Use the `-f` / `--file` option to specify the build definition file to use. The file can be an HCL, JSON or Compose file. If multiple files are specified, all are read and the build configurations are combined. Alternatively, the environment variable `BUILDX_BAKE_FILE` can be used to specify the build definition to use. This is mutually exclusive with `-f` / `--file`; if both are specified, the environment variable is ignored. Multiple definitions can be specified by separating them with the system's path separator (typically `;` on Windows and `:` elsewhere), but can be changed with `BUILDX_BAKE_PATH_SEPARATOR`. By default, local directory build contexts in Bake files are resolved from the current working directory. To opt in to resolving local directory build contexts from the Bake file that defines each path, set `BUILDX_BAKE_FILE_RELATIVE_PATHS=1`. Compose files use the first Compose file directory as the base, which matches Compose project directory semantics. Use the `cwd://` prefix for paths that should remain relative to the current working directory. You can pass the names of the targets to build, to build only specific target(s). The following example builds the `db` and `webapp-release` targets that are defined in the `docker-bake.dev.hcl` file: ```hcl # docker-bake.dev.hcl group "default" { targets = ["db", "webapp-dev"] } target "webapp-dev" { dockerfile = "Dockerfile.webapp" tags = ["docker.io/username/webapp"] } target "webapp-release" { inherits = ["webapp-dev"] platforms = ["linux/amd64", "linux/arm64"] } target "db" { dockerfile = "Dockerfile.db" tags = ["docker.io/username/db"] } ``` ```console $ docker buildx bake -f docker-bake.dev.hcl db webapp-release ``` See the [Bake file reference](/build/bake/reference/) for more details. ### List targets and variables (--list) {#list} The `--list` flag displays all available targets or variables in the Bake configuration, along with a description (if set using the `description` property in the Bake file). To list all targets: ```console {title="List targets"} $ docker buildx bake --list=targets TARGET DESCRIPTION binaries default binaries update-docs validate validate-golangci Validate .golangci.yml schema (does not run Go linter) ``` To list variables: ```console $ docker buildx bake --list=variables VARIABLE TYPE VALUE DESCRIPTION REGISTRY string docker.io/username Registry and namespace IMAGE_NAME string my-app Image name GO_VERSION DEBUG bool false Add debug symbols ``` Variable types will be shown when set using the `type` property in the Bake file. The `--list=variables` option displays variables defined in the Bake file, including their descriptions and default values. ### Example: listing variables with descriptions ```hcl variable "GO_VERSION" { default = "1.22" description = "Go version used for building the application" } ``` ```console $ docker buildx bake --list=variables NAME DESCRIPTION DEFAULT GO_VERSION Go version used for building the application 1.22 ``` By default, the output of `docker buildx bake --list` is presented in a table format. Alternatively, you can use a long-form CSV syntax and specify a `format` attribute to output the list in JSON. ```console $ docker buildx bake --list=type=targets,format=json ``` ### Load images into Docker (--load) {#load} The `--load` flag is a convenience shorthand for adding an image export of type `docker`: ```console --load ≈ --set=*.output=type=docker ``` However, its behavior is conditional: - If the build definition has no output defined, `--load` adds `type=docker`. - If the build definition’s outputs are `docker`, `image`, `registry`, `oci`, `--load` will add a `type=docker` export if one is not already present. - If the build definition contains `local` or `tar` outputs, `--load` does nothing. It will not override those outputs. For example, with the following bake file: ```hcl target "default" { output = ["type=tar,dest=hi.tar"] } ``` With `--load`: ```console $ docker buildx bake --load --print ... "output": [ { "dest": "hi.tar" "type": "tar", } ] ``` The `tar` output remains unchanged. ### Write build results metadata to a file (--metadata-file) {#metadata-file} Similar to [`buildx build --metadata-file`](/reference/cli/docker/buildx/build/#metadata-file) but writes a map of results for each target such as: ```hcl # docker-bake.hcl group "default" { targets = ["db", "webapp-dev"] } target "db" { dockerfile = "Dockerfile.db" tags = ["docker.io/username/db"] } target "webapp-dev" { dockerfile = "Dockerfile.webapp" tags = ["docker.io/username/webapp"] } ``` ```console $ docker buildx bake --load --metadata-file metadata.json . $ cat metadata.json ``` ```json { "buildx.build.warnings": {}, "db": { "buildx.build.provenance": {}, "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" }, "webapp-dev": { "buildx.build.provenance": {}, "buildx.build.ref": "mybuilder/mybuilder0/kamngmcgyzebqxwu98b4lfv3n", "containerimage.config.digest": "sha256:9651cc2b3c508f697c9c43b67b64c8359c2865c019e680aac1c11f4b875b67e0", "containerimage.descriptor": { "annotations": { "config.digest": "sha256:9651cc2b3c508f697c9c43b67b64c8359c2865c019e680aac1c11f4b875b67e0", "org.opencontainers.image.created": "2022-02-08T21:28:15Z" }, "digest": "sha256:6d9ac9237a84afe1516540f40a0fafdc86859b2141954b4d643af7066d598b74", "mediaType": "application/vnd.oci.image.manifest.v1+json", "size": 506 }, "containerimage.digest": "sha256:6d9ac9237a84afe1516540f40a0fafdc86859b2141954b4d643af7066d598b74" } } ``` > [!NOTE] > Build record [provenance](/build/metadata/attestations/slsa-provenance/#provenance-attestation-example) > (`buildx.build.provenance`) includes minimal provenance by default. Set the > `BUILDX_METADATA_PROVENANCE` environment variable to customize this behavior: > * `min` sets minimal provenance (default). > * `max` sets full provenance. > * `disabled`, `false` or `0` does not set any provenance. > [!NOTE] > Build warnings (`buildx.build.warnings`) are not included by default. Set the > `BUILDX_METADATA_WARNINGS` environment variable to `1` or `true` to > include them. ### Don't use cache when building the image (--no-cache) {#no-cache} Same as `build --no-cache`. Don't use cache when building the image. ### Print the options without building (--print) {#print} Prints the resulting options of the targets desired to be built, in a JSON format, without starting a build. ```console $ docker buildx bake -f docker-bake.hcl --print db { "group": { "default": { "targets": [ "db" ] } }, "target": { "db": { "context": "./", "dockerfile": "Dockerfile", "tags": [ "docker.io/tiborvass/db" ] } } } ``` ### Set type of progress output (--progress) {#progress} Same as [`build --progress`](/reference/cli/docker/buildx/build/#progress). ### Create provenance attestations (--provenance) {#provenance} Same as [`build --provenance`](/reference/cli/docker/buildx/build/#provenance). ### Always attempt to pull a newer version of the image (--pull) {#pull} Same as `build --pull`. ### Push images to a registry (--push) {#push} The `--push` flag follows the same logic as `--load`: - If no outputs are defined, it adds a `type=image,push=true` export. - For existing `image` outputs, it sets `push=true`. - If outputs are set to `local` or `tar`, it does not override them. ### Create SBOM attestations (--sbom) {#sbom} Same as [`build --sbom`](/reference/cli/docker/buildx/build/#sbom). ### Override target configurations from command line (--set) {#set} ``` --set targetpattern.key[.subkey]=value ``` Override target configurations from command line. The pattern matching syntax is defined in https://golang.org/pkg/path/#Match. ```console $ docker buildx bake --set target.arg.mybuildarg=value $ docker buildx bake --set target.platform=linux/arm64 $ docker buildx bake --set foo*.arg.mybuildarg=value # overrides build arg for all targets starting with 'foo' $ docker buildx bake --set *.platform=linux/arm64 # overrides platforms for all targets $ docker buildx bake --set foo*.no-cache # bypass caching only for targets starting with 'foo' $ docker buildx bake --set target.platform+=linux/arm64 # appends 'linux/arm64' to the platform list $ docker buildx bake --set target.contexts.bar=../bar # overrides 'bar' named context $ docker buildx bake --set target.resource.memory=2g # overrides memory resource limit $ docker buildx bake --set target.secret.aws=env=AWS # overrides source for an existing secret $ docker buildx bake --set target.tag= # clears all tag values ``` > [!NOTE] > > `--set` is a repeatable flag. For array fields such as `tag`, repeat `--set` > to provide multiple values or use the `+=` operator to append without > replacing. Array literal syntax like `--set target.tag=[a,b]` is not > supported. For array fields, a non-append assignment with an empty value > clears values from the Bake definition and earlier `--set` flags. Subsequent > assignments or appends add values to the cleared array. You can override the following fields: * `annotation` * `attest` * `arg.` * `cache-from` * `cache-to` * `call` * `context` * `contexts.` * `dockerfile` * `entitlement` * `extra-host.` * `label.` * `load` * `no-cache` * `no-cache-filter` * `network` * `output` * `platform` * `policy` * `pull` * `push` * `resource.` * `secret` * `secret.` * `shm-size` * `ssh` * `tag` * `target` * `ulimit` You can append using `+=` operator for the following fields: * `annotation`¹ * `attest`¹ * `cache-from` * `cache-to` * `entitlement`¹ * `no-cache-filter` * `output` * `platform` * `policy` * `secret` * `ssh` * `tag` * `ulimit` > [!NOTE] > ¹ These fields already append by default. Override keys use singular names. Existing plural Bake field names and historical `--set` spellings remain supported as aliases: | Alias | Canonical key | |----------------|---------------| | `annotations` | `annotation` | | `args` | `arg` | | `entitlements` | `entitlement` | | `extra-hosts` | `extra-host` | | `labels` | `label` | | `platforms` | `platform` | | `resources` | `resource` | | `secrets` | `secret` | | `tags` | `tag` | | `ulimits` | `ulimit` | Aliases are normalized before overrides are applied, so they can be mixed with canonical keys in repeated `--set` options. `context` and `contexts` are not aliases: `context` sets the build context, while `contexts.` sets a named context. `secret.` also has separate semantics: it changes the source of a secret that is already declared by the target. The plural alias does not support this form; `secrets.` is invalid. #### Inline values for composable attributes Composable fields such as `ssh`, `secret`, `output`, `cache-to`, `cache-from`, `attest`, and `annotation` accept a list of object values in a Bake file. When you override these fields with `--set`, provide each value using the same inline string syntax as the corresponding build flag, not the HCL object form. The override replaces or appends to the list as a whole and does not address individual object fields with a subkey. Only `arg`, `contexts`, `extra-host`, `label`, `resource`, and `secret` support entry-addressed subkeys. For example, use `--set target.arg.MYARG=value` to override one build argument. As described above, `secret.` changes the source of an existing secret rather than an object field. For example, to set the SSH agent socket or key for a target, use the same `id=path` form accepted by [`build --ssh`](/reference/cli/docker/buildx/build/#ssh): ```console $ docker buildx bake --set "*.ssh=default=$HOME/.ssh/id_ed25519" ``` To expose multiple paths for the same `id`, separate them with commas in the second part: ```console $ docker buildx bake --set "*.ssh=default=$HOME/.ssh/id_ed25519,$HOME/.ssh/id_rsa" ``` Your shell expands `$HOME` before buildx sees the value. The equivalent Bake file definition uses the [`homedir`](/build/bake/stdlib/#homedir) HCL function: ```hcl target "default" { ssh = [{ id = "default", paths = ["${homedir()}/.ssh/id_ed25519", "${homedir()}/.ssh/id_rsa"] }] } ```