docker-docs/data/cli/buildx/docker_buildx_bake.yaml

command: docker buildx bake
aliases: docker buildx bake, docker buildx f
short: Build from a file
long: |-
    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.

    > [!NOTE]
    > `buildx bake` command may receive backwards incompatible features in the future
    > if needed. We are looking for feedback on improving the command and extending
    > the functionality further.
usage: docker buildx bake [OPTIONS] [TARGET...]
pname: docker buildx
plink: docker_buildx.yaml
options:
    - option: allow
      value_type: stringArray
      default_value: '[]'
      description: Allow build to access specified resources
      details_url: '#allow'
      deprecated: false
      hidden: false
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
    - option: call
      value_type: string
      default_value: build
      description: Set method for evaluating build (`check`, `outline`, `targets`)
      details_url: '#call'
      deprecated: false
      hidden: false
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
    - option: check
      value_type: bool
      description: Shorthand for `--call=check`
      details_url: '#check'
      deprecated: false
      hidden: false
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
    - option: file
      shorthand: f
      value_type: stringArray
      default_value: '[]'
      description: Build definition file
      details_url: '#file'
      deprecated: false
      hidden: false
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
    - option: list
      value_type: string
      description: List targets or variables
      details_url: '#list'
      deprecated: false
      hidden: false
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
    - option: list-targets
      value_type: bool
      default_value: "false"
      description: List available targets
      deprecated: true
      hidden: true
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
    - option: list-variables
      value_type: bool
      default_value: "false"
      description: List defined variables
      deprecated: true
      hidden: true
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
    - option: load
      value_type: bool
      default_value: "false"
      description: Shorthand for `--set=*.output=type=docker`. Conditional.
      details_url: '#load'
      deprecated: false
      hidden: false
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
    - option: metadata-file
      value_type: string
      description: Write build result metadata to a file
      details_url: '#metadata-file'
      deprecated: false
      hidden: false
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
    - option: no-cache
      value_type: bool
      default_value: "false"
      description: Do not use cache when building the image
      details_url: '#no-cache'
      deprecated: false
      hidden: false
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
    - option: print
      value_type: bool
      default_value: "false"
      description: Print the options without building
      details_url: '#print'
      deprecated: false
      hidden: false
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
    - option: progress
      value_type: string
      default_value: auto
      description: |
        Set type of progress output (`auto`, `none`,  `plain`, `quiet`, `rawjson`, `tty`). Use plain to show container output
      details_url: '#progress'
      deprecated: false
      hidden: false
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
    - option: provenance
      value_type: string
      description: Shorthand for `--set=*.attest=type=provenance`
      details_url: '#provenance'
      deprecated: false
      hidden: false
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
    - option: pull
      value_type: bool
      default_value: "false"
      description: Always attempt to pull all referenced images
      details_url: '#pull'
      deprecated: false
      hidden: false
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
    - option: push
      value_type: bool
      default_value: "false"
      description: Shorthand for `--set=*.output=type=registry`. Conditional.
      details_url: '#push'
      deprecated: false
      hidden: false
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
    - option: sbom
      value_type: string
      description: Shorthand for `--set=*.attest=type=sbom`
      details_url: '#sbom'
      deprecated: false
      hidden: false
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
    - option: set
      value_type: stringArray
      default_value: '[]'
      description: Override target value (e.g., `targetpattern.key=value`)
      details_url: '#set'
      deprecated: false
      hidden: false
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
    - option: var
      value_type: stringArray
      default_value: '[]'
      description: Set a variable value (e.g., `name=value`)
      deprecated: false
      hidden: false
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
inherited_options:
    - option: builder
      value_type: string
      description: Override the configured builder instance
      details_url: '#builder'
      deprecated: false
      hidden: false
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
    - option: debug
      shorthand: D
      value_type: bool
      default_value: "false"
      description: Enable debug logging
      deprecated: false
      hidden: false
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
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=<path|*>` - Grant read and write access to files outside of the
      working directory.
    - `--allow fs.read=<path|*>` - Grant read access to files outside of the
      working directory.
    - `--allow fs.write=<path|*>` - 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.

    ### 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).

    ### 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`.

    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              <null>
    DEBUG         bool      false                Add debug symbols
    ```

    Variable types will be shown when set using the `type` property in the Bake file.

    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.args.mybuildarg=value
    $ docker buildx bake --set target.platform=linux/arm64
    $ docker buildx bake --set foo*.args.mybuildarg=value   # overrides build arg for all targets starting with 'foo'
    $ docker buildx bake --set *.platform=linux/arm64       # overrides platform 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
    ```

    > [!NOTE]
    >
    > `--set` is a repeatable flag. For array fields such as `tags`, repeat `--set`
    > to provide multiple values or use the `+=` operator to append without
    > replacing. Array literal syntax like `--set target.tags=[a,b]` is not
    > supported.

    You can override the following fields:

    * `annotations`
    * `attest`
    * `args`
    * `cache-from`
    * `cache-to`
    * `call`
    * `context`
    * `contexts`
    * `dockerfile`
    * `entitlements`
    * `extra-hosts`
    * `labels`
    * `load`
    * `no-cache`
    * `no-cache-filter`
    * `output`
    * `platform`
    * `pull`
    * `push`
    * `secrets`
    * `ssh`
    * `tags`
    * `target`

    You can append using `+=` operator for the following fields:

    * `annotations`¹
    * `attest`¹
    * `cache-from`
    * `cache-to`
    * `entitlements`¹
    * `no-cache-filter`
    * `output`
    * `platform`
    * `secrets`
    * `ssh`
    * `tags`

    > [!NOTE]
    > ¹ These fields already append by default.
deprecated: false
hidden: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false