diff --git a/commands/build.go b/commands/build.go index c945b38f..374f4d54 100644 --- a/commands/build.go +++ b/commands/build.go @@ -38,7 +38,6 @@ import ( "github.com/docker/buildx/util/osutil" "github.com/docker/buildx/util/progress" "github.com/docker/buildx/util/tracing" - "github.com/docker/cli-docs-tool/annotation" "github.com/docker/cli/cli" "github.com/docker/cli/cli/command" dockeropts "github.com/docker/cli/opts" @@ -529,10 +528,12 @@ func buildCmd(dockerCli command.Cli, rootOpts *rootOptions, debugConfig *debug.D options := &buildOptions{} cmd := &cobra.Command{ - Use: "build [OPTIONS] PATH | URL | -", - Aliases: []string{"b"}, - Short: "Start a build", - Args: cli.ExactArgs(1), + Use: "build [OPTIONS] PATH | URL | -", + Short: "Start a build", + Args: cli.ExactArgs(1), + Annotations: map[string]string{ + "aliases": "docker build, docker builder build, docker image build, docker buildx b", + }, RunE: func(cmd *cobra.Command, args []string) error { options.contextPath = args[0] options.builder = rootOpts.builder @@ -571,7 +572,6 @@ func buildCmd(dockerCli command.Cli, rootOpts *rootOptions, debugConfig *debug.D flags := cmd.Flags() flags.StringSliceVar(&options.extraHosts, "add-host", []string{}, `Add a custom host-to-IP mapping (format: "host:ip")`) - flags.SetAnnotation("add-host", annotation.ExternalURL, []string{"https://docs.docker.com/reference/cli/docker/image/build/#add-host"}) flags.StringSliceVar(&options.allow, "allow", []string{}, `Allow extra privileged entitlement (e.g., "network.host", "security.insecure")`) @@ -584,12 +584,10 @@ func buildCmd(dockerCli command.Cli, rootOpts *rootOptions, debugConfig *debug.D flags.StringArrayVar(&options.cacheTo, "cache-to", []string{}, `Cache export destinations (e.g., "user/app:cache", "type=local,dest=path/to/dir")`) flags.StringVar(&options.cgroupParent, "cgroup-parent", "", `Set the parent cgroup for the "RUN" instructions during build`) - flags.SetAnnotation("cgroup-parent", annotation.ExternalURL, []string{"https://docs.docker.com/reference/cli/docker/image/build/#cgroup-parent"}) flags.StringArrayVar(&options.contexts, "build-context", []string{}, "Additional build contexts (e.g., name=path)") flags.StringVarP(&options.dockerfileName, "file", "f", "", `Name of the Dockerfile (default: "PATH/Dockerfile")`) - flags.SetAnnotation("file", annotation.ExternalURL, []string{"https://docs.docker.com/reference/cli/docker/image/build/#file"}) flags.StringVar(&options.imageIDFile, "iidfile", "", "Write the image ID to a file") @@ -616,10 +614,8 @@ func buildCmd(dockerCli command.Cli, rootOpts *rootOptions, debugConfig *debug.D flags.StringArrayVar(&options.ssh, "ssh", []string{}, `SSH agent socket or keys to expose to the build (format: "default|[=|[,]]")`) flags.StringArrayVarP(&options.tags, "tag", "t", []string{}, `Name and optionally a tag (format: "name:tag")`) - flags.SetAnnotation("tag", annotation.ExternalURL, []string{"https://docs.docker.com/reference/cli/docker/image/build/#tag"}) flags.StringVar(&options.target, "target", "", "Set the target build stage to build") - flags.SetAnnotation("target", annotation.ExternalURL, []string{"https://docs.docker.com/reference/cli/docker/image/build/#target"}) options.ulimits = dockeropts.NewUlimitOpt(nil) flags.Var(options.ulimits, "ulimit", "Ulimit options") diff --git a/docs/reference/buildx_build.md b/docs/reference/buildx_build.md index ea74ea20..2ca8dce8 100644 --- a/docs/reference/buildx_build.md +++ b/docs/reference/buildx_build.md @@ -9,49 +9,49 @@ Start a build ### Aliases -`docker buildx build`, `docker buildx b` +`docker build`, `docker builder build`, `docker image build`, `docker buildx b` ### Options -| Name | Type | Default | Description | -|:---------------------------------------------------------------------------------------------------------------------------------------------------|:--------------|:----------|:----------------------------------------------------------------------------------------------------| -| [`--add-host`](https://docs.docker.com/reference/cli/docker/image/build/#add-host) | `stringSlice` | | Add a custom host-to-IP mapping (format: `host:ip`) | -| [`--allow`](#allow) | `stringSlice` | | Allow extra privileged entitlement (e.g., `network.host`, `security.insecure`) | -| [`--annotation`](#annotation) | `stringArray` | | Add annotation to the image | -| [`--attest`](#attest) | `stringArray` | | Attestation parameters (format: `type=sbom,generator=image`) | -| [`--build-arg`](#build-arg) | `stringArray` | | Set build-time variables | -| [`--build-context`](#build-context) | `stringArray` | | Additional build contexts (e.g., name=path) | -| [`--builder`](#builder) | `string` | | Override the configured builder instance | -| [`--cache-from`](#cache-from) | `stringArray` | | External cache sources (e.g., `user/app:cache`, `type=local,src=path/to/dir`) | -| [`--cache-to`](#cache-to) | `stringArray` | | Cache export destinations (e.g., `user/app:cache`, `type=local,dest=path/to/dir`) | -| `--call` | `string` | `build` | Set method for evaluating build (`check`, `outline`, `targets`) | -| [`--cgroup-parent`](https://docs.docker.com/reference/cli/docker/image/build/#cgroup-parent) | `string` | | Set the parent cgroup for the `RUN` instructions during build | -| `--check` | | | Shorthand for `--call=check` | -| `--detach` | | | Detach buildx server (supported only on linux) (EXPERIMENTAL) | -| [`-f`](https://docs.docker.com/reference/cli/docker/image/build/#file), [`--file`](https://docs.docker.com/reference/cli/docker/image/build/#file) | `string` | | Name of the Dockerfile (default: `PATH/Dockerfile`) | -| `--iidfile` | `string` | | Write the image ID to a file | -| `--label` | `stringArray` | | Set metadata for an image | -| [`--load`](#load) | | | Shorthand for `--output=type=docker` | -| [`--metadata-file`](#metadata-file) | `string` | | Write build result metadata to a file | -| `--network` | `string` | `default` | Set the networking mode for the `RUN` instructions during build | -| `--no-cache` | | | Do not use cache when building the image | -| [`--no-cache-filter`](#no-cache-filter) | `stringArray` | | Do not cache specified stages | -| [`-o`](#output), [`--output`](#output) | `stringArray` | | Output destination (format: `type=local,dest=path`) | -| [`--platform`](#platform) | `stringArray` | | Set target platform for build | -| [`--progress`](#progress) | `string` | `auto` | Set type of progress output (`auto`, `plain`, `tty`, `rawjson`). Use plain to show container output | -| [`--provenance`](#provenance) | `string` | | Shorthand for `--attest=type=provenance` | -| `--pull` | | | Always attempt to pull all referenced images | -| [`--push`](#push) | | | Shorthand for `--output=type=registry` | -| `-q`, `--quiet` | | | Suppress the build output and print image ID on success | -| `--root` | `string` | | Specify root directory of server to connect (EXPERIMENTAL) | -| [`--sbom`](#sbom) | `string` | | Shorthand for `--attest=type=sbom` | -| [`--secret`](#secret) | `stringArray` | | Secret to expose to the build (format: `id=mysecret[,src=/local/secret]`) | -| `--server-config` | `string` | | Specify buildx server config file (used only when launching new server) (EXPERIMENTAL) | -| [`--shm-size`](#shm-size) | `bytes` | `0` | Shared memory size for build containers | -| [`--ssh`](#ssh) | `stringArray` | | SSH agent socket or keys to expose to the build (format: `default\|[=\|[,]]`) | -| [`-t`](https://docs.docker.com/reference/cli/docker/image/build/#tag), [`--tag`](https://docs.docker.com/reference/cli/docker/image/build/#tag) | `stringArray` | | Name and optionally a tag (format: `name:tag`) | -| [`--target`](https://docs.docker.com/reference/cli/docker/image/build/#target) | `string` | | Set the target build stage to build | -| [`--ulimit`](#ulimit) | `ulimit` | | Ulimit options | +| Name | Type | Default | Description | +|:----------------------------------------|:--------------|:----------|:----------------------------------------------------------------------------------------------------| +| [`--add-host`](#add-host) | `stringSlice` | | Add a custom host-to-IP mapping (format: `host:ip`) | +| [`--allow`](#allow) | `stringSlice` | | Allow extra privileged entitlement (e.g., `network.host`, `security.insecure`) | +| [`--annotation`](#annotation) | `stringArray` | | Add annotation to the image | +| [`--attest`](#attest) | `stringArray` | | Attestation parameters (format: `type=sbom,generator=image`) | +| [`--build-arg`](#build-arg) | `stringArray` | | Set build-time variables | +| [`--build-context`](#build-context) | `stringArray` | | Additional build contexts (e.g., name=path) | +| [`--builder`](#builder) | `string` | | Override the configured builder instance | +| [`--cache-from`](#cache-from) | `stringArray` | | External cache sources (e.g., `user/app:cache`, `type=local,src=path/to/dir`) | +| [`--cache-to`](#cache-to) | `stringArray` | | Cache export destinations (e.g., `user/app:cache`, `type=local,dest=path/to/dir`) | +| `--call` | `string` | `build` | Set method for evaluating build (`check`, `outline`, `targets`) | +| [`--cgroup-parent`](#cgroup-parent) | `string` | | Set the parent cgroup for the `RUN` instructions during build | +| `--check` | | | Shorthand for `--call=check` | +| `--detach` | | | Detach buildx server (supported only on linux) (EXPERIMENTAL) | +| [`-f`](#file), [`--file`](#file) | `string` | | Name of the Dockerfile (default: `PATH/Dockerfile`) | +| `--iidfile` | `string` | | Write the image ID to a file | +| `--label` | `stringArray` | | Set metadata for an image | +| [`--load`](#load) | | | Shorthand for `--output=type=docker` | +| [`--metadata-file`](#metadata-file) | `string` | | Write build result metadata to a file | +| [`--network`](#network) | `string` | `default` | Set the networking mode for the `RUN` instructions during build | +| `--no-cache` | | | Do not use cache when building the image | +| [`--no-cache-filter`](#no-cache-filter) | `stringArray` | | Do not cache specified stages | +| [`-o`](#output), [`--output`](#output) | `stringArray` | | Output destination (format: `type=local,dest=path`) | +| [`--platform`](#platform) | `stringArray` | | Set target platform for build | +| [`--progress`](#progress) | `string` | `auto` | Set type of progress output (`auto`, `plain`, `tty`, `rawjson`). Use plain to show container output | +| [`--provenance`](#provenance) | `string` | | Shorthand for `--attest=type=provenance` | +| `--pull` | | | Always attempt to pull all referenced images | +| [`--push`](#push) | | | Shorthand for `--output=type=registry` | +| `-q`, `--quiet` | | | Suppress the build output and print image ID on success | +| `--root` | `string` | | Specify root directory of server to connect (EXPERIMENTAL) | +| [`--sbom`](#sbom) | `string` | | Shorthand for `--attest=type=sbom` | +| [`--secret`](#secret) | `stringArray` | | Secret to expose to the build (format: `id=mysecret[,src=/local/secret]`) | +| `--server-config` | `string` | | Specify buildx server config file (used only when launching new server) (EXPERIMENTAL) | +| [`--shm-size`](#shm-size) | `bytes` | `0` | Shared memory size for build containers | +| [`--ssh`](#ssh) | `stringArray` | | SSH agent socket or keys to expose to the build (format: `default\|[=\|[,]]`) | +| [`-t`](#tag), [`--tag`](#tag) | `stringArray` | | Name and optionally a tag (format: `name:tag`) | +| [`--target`](#target) | `string` | | Set the target build stage to build | +| [`--ulimit`](#ulimit) | `ulimit` | | Ulimit options | @@ -61,15 +61,36 @@ Flags marked with `[experimental]` need to be explicitly enabled by setting the ## 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](https://docs.docker.com/reference/cli/docker/image/build/). -This page describes a subset of the new flags. +The `docker buildx build` command starts a build using BuildKit. ## Examples +### 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 named +`my-hostname` and `my_hostname_v6`: + +```console +$ docker buildx build --add-host my_hostname=8.8.8.8 --add-host my_hostname_v6=2001:4860:4860::8888 . +``` + +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. + +```console +$ docker buildx build --add-host host.docker.internal=host-gateway . +``` + +You can wrap an IPv6 address in square brackets. +`=` and `:` are both valid separators. +Both formats in the following example are valid: + +```console +$ docker buildx build --add-host my-hostname:10.180.0.1 --add-host my-hostname_v6=[2001:4860:4860::8888] . +``` + ### Create annotations (--annotation) ```text @@ -165,7 +186,40 @@ $ docker buildx build --allow security.insecure . ### Set build-time variables (--build-arg) -Same as [`docker build` command](https://docs.docker.com/reference/cli/docker/image/build/#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: + +```console +$ docker buildx build --build-arg HTTP_PROXY=http://10.20.30.2:1234 --build-arg FTP_PROXY=http://40.50.60.5:4567 . +``` + +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 the`ARG` lines from the +Dockerfile. + +For detailed information on using `ARG` and `ENV` instructions, see the +[Dockerfile reference](https://docs.docker.com/reference/dockerfile/). + +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: + +```console +$ export HTTP_PROXY=http://10.20.30.2:1234 +$ docker buildx build --build-arg HTTP_PROXY . +``` + +This example is similar to how `docker run -e` works. Refer to the [`docker run` documentation](container_run.md#env) +for more information. There are also useful built-in build arguments, such as: @@ -310,6 +364,27 @@ $ 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 +### 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 the +[corresponding `docker run` flag](container_run.md#cgroup-parent). + +### Specify a Dockerfile (-f, --file) + +```console +$ docker buildx build -f . +``` + +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`. + +```console +$ cat Dockerfile | docker buildx build -f - . +``` + ### Load the single-platform build result to `docker images` (--load) Shorthand for [`--output=type=docker`](#docker). Will automatically load the @@ -350,9 +425,20 @@ $ cat metadata.json > Build record [provenance](https://docs.docker.com/build/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. +> +> - `min` sets minimal provenance (default). +> - `max` sets full provenance. +> - `disabled`, `false` or `0` doesn't set any provenance. + +### 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 the [Dockerfile reference](https://docs.docker.com/reference/dockerfile/#run---network). > **Note** > @@ -421,17 +507,19 @@ The arguments for the `--no-cache-filter` flag must be names of stages. -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. +Sets the export action for the build result. The default output, when using the +`docker` [build driver](https://docs.docker.com/build/drivers/), 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 currently only supports local, tarball exporter and -image exporter. `docker-container` driver supports all the exporters. +Buildx with `docker` driver only supports the local, tarball, and image +[exporters](https://docs.docker.com/build/exporters/). The `docker-container` +driver supports all 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`. +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. ```console $ docker buildx build -o . . @@ -442,12 +530,17 @@ $ docker buildx build -o type=docker,dest=- . > myimage.tar $ docker buildx build -t tonistiigi/foo -o type=registry ``` -> **Note ** -> -> Since BuildKit v0.13.0 multiple outputs can be specified by repeating the flag. +You can export multiple outputs by repeating the flag. Supported exported types are: +- [`local`](#local) +- [`tar`](#tar) +- [`oci`](#oci) +- [`docker`](#docker) +- [`image`](#image) +- [`registry`](#registry) + #### `local` The `local` export type writes all result files to a directory on the client. The @@ -552,13 +645,12 @@ 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`](https://en.wikipedia.org/wiki/Binfmt_misc) launchers for secondary architectures, buildx will pick them up automatically. -Docker desktop releases come with `binfmt_misc` automatically configured for `arm64` +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. Refer to the [`docker build` -documentation](https://docs.docker.com/reference/dockerfile/#automatic-platform-args-in-the-global-scope) +`TARGETPLATFORM` build argument. Refer to the [Dockerfile reference](https://docs.docker.com/reference/dockerfile/#automatic-platform-args-in-the-global-scope) for the full description of automatic platform argument variants . You can find the formatting definition for the platform specifier in the @@ -751,6 +843,46 @@ $ ssh-add ~/.ssh/id_rsa $ docker buildx build --ssh default=$SSH_AUTH_SOCK . ``` +### Tag an image (-t, --tag) + +```console +$ docker buildx build -t docker/apache:2.0 . +``` + +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](https://docs.docker.com/reference/cli/docker/image/tag/). + +You can apply multiple tags to an image. For example, you can apply the `latest` +tag 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` and +`docker/fedora-jboss:v2.1`, use the following: + +```console +$ docker buildx build -t docker/fedora-jboss:latest -t docker/fedora-jboss:v2.1 . +``` + +### Specifying target build stage (--target) + +When building a Dockerfile with multiple build stages, use the `--target` +option to specify an intermediate build stage by name as a final stage for the +resulting image. The builder skips commands after the target stage. + +```dockerfile +FROM debian AS build-env +# ... + +FROM alpine AS production-env +# ... +``` + +```console +$ docker buildx build -t mybuildimage --target build-env . +``` + ### Set ulimits (--ulimit) `--ulimit` overrides the default ulimits of build's containers when using `RUN` diff --git a/docs/reference/buildx_debug_build.md b/docs/reference/buildx_debug_build.md index 30ef7b87..de10ac0b 100644 --- a/docs/reference/buildx_debug_build.md +++ b/docs/reference/buildx_debug_build.md @@ -5,49 +5,49 @@ Start a build ### Aliases -`docker buildx debug build`, `docker buildx debug b` +`docker build`, `docker builder build`, `docker image build`, `docker buildx b` ### Options -| Name | Type | Default | Description | -|:---------------------------------------------------------------------------------------------------------------------------------------------------|:--------------|:----------|:----------------------------------------------------------------------------------------------------| -| [`--add-host`](https://docs.docker.com/reference/cli/docker/image/build/#add-host) | `stringSlice` | | Add a custom host-to-IP mapping (format: `host:ip`) | -| `--allow` | `stringSlice` | | Allow extra privileged entitlement (e.g., `network.host`, `security.insecure`) | -| `--annotation` | `stringArray` | | Add annotation to the image | -| `--attest` | `stringArray` | | Attestation parameters (format: `type=sbom,generator=image`) | -| `--build-arg` | `stringArray` | | Set build-time variables | -| `--build-context` | `stringArray` | | Additional build contexts (e.g., name=path) | -| `--builder` | `string` | | Override the configured builder instance | -| `--cache-from` | `stringArray` | | External cache sources (e.g., `user/app:cache`, `type=local,src=path/to/dir`) | -| `--cache-to` | `stringArray` | | Cache export destinations (e.g., `user/app:cache`, `type=local,dest=path/to/dir`) | -| `--call` | `string` | `build` | Set method for evaluating build (`check`, `outline`, `targets`) | -| [`--cgroup-parent`](https://docs.docker.com/reference/cli/docker/image/build/#cgroup-parent) | `string` | | Set the parent cgroup for the `RUN` instructions during build | -| `--check` | | | Shorthand for `--call=check` | -| `--detach` | | | Detach buildx server (supported only on linux) (EXPERIMENTAL) | -| [`-f`](https://docs.docker.com/reference/cli/docker/image/build/#file), [`--file`](https://docs.docker.com/reference/cli/docker/image/build/#file) | `string` | | Name of the Dockerfile (default: `PATH/Dockerfile`) | -| `--iidfile` | `string` | | Write the image ID to a file | -| `--label` | `stringArray` | | Set metadata for an image | -| `--load` | | | Shorthand for `--output=type=docker` | -| `--metadata-file` | `string` | | Write build result metadata to a file | -| `--network` | `string` | `default` | Set the networking mode for the `RUN` instructions during build | -| `--no-cache` | | | Do not use cache when building the image | -| `--no-cache-filter` | `stringArray` | | Do not cache specified stages | -| `-o`, `--output` | `stringArray` | | Output destination (format: `type=local,dest=path`) | -| `--platform` | `stringArray` | | Set target platform for build | -| `--progress` | `string` | `auto` | Set type of progress output (`auto`, `plain`, `tty`, `rawjson`). Use plain to show container output | -| `--provenance` | `string` | | Shorthand for `--attest=type=provenance` | -| `--pull` | | | Always attempt to pull all referenced images | -| `--push` | | | Shorthand for `--output=type=registry` | -| `-q`, `--quiet` | | | Suppress the build output and print image ID on success | -| `--root` | `string` | | Specify root directory of server to connect (EXPERIMENTAL) | -| `--sbom` | `string` | | Shorthand for `--attest=type=sbom` | -| `--secret` | `stringArray` | | Secret to expose to the build (format: `id=mysecret[,src=/local/secret]`) | -| `--server-config` | `string` | | Specify buildx server config file (used only when launching new server) (EXPERIMENTAL) | -| `--shm-size` | `bytes` | `0` | Shared memory size for build containers | -| `--ssh` | `stringArray` | | SSH agent socket or keys to expose to the build (format: `default\|[=\|[,]]`) | -| [`-t`](https://docs.docker.com/reference/cli/docker/image/build/#tag), [`--tag`](https://docs.docker.com/reference/cli/docker/image/build/#tag) | `stringArray` | | Name and optionally a tag (format: `name:tag`) | -| [`--target`](https://docs.docker.com/reference/cli/docker/image/build/#target) | `string` | | Set the target build stage to build | -| `--ulimit` | `ulimit` | | Ulimit options | +| Name | Type | Default | Description | +|:--------------------|:--------------|:----------|:----------------------------------------------------------------------------------------------------| +| `--add-host` | `stringSlice` | | Add a custom host-to-IP mapping (format: `host:ip`) | +| `--allow` | `stringSlice` | | Allow extra privileged entitlement (e.g., `network.host`, `security.insecure`) | +| `--annotation` | `stringArray` | | Add annotation to the image | +| `--attest` | `stringArray` | | Attestation parameters (format: `type=sbom,generator=image`) | +| `--build-arg` | `stringArray` | | Set build-time variables | +| `--build-context` | `stringArray` | | Additional build contexts (e.g., name=path) | +| `--builder` | `string` | | Override the configured builder instance | +| `--cache-from` | `stringArray` | | External cache sources (e.g., `user/app:cache`, `type=local,src=path/to/dir`) | +| `--cache-to` | `stringArray` | | Cache export destinations (e.g., `user/app:cache`, `type=local,dest=path/to/dir`) | +| `--call` | `string` | `build` | Set method for evaluating build (`check`, `outline`, `targets`) | +| `--cgroup-parent` | `string` | | Set the parent cgroup for the `RUN` instructions during build | +| `--check` | | | Shorthand for `--call=check` | +| `--detach` | | | Detach buildx server (supported only on linux) (EXPERIMENTAL) | +| `-f`, `--file` | `string` | | Name of the Dockerfile (default: `PATH/Dockerfile`) | +| `--iidfile` | `string` | | Write the image ID to a file | +| `--label` | `stringArray` | | Set metadata for an image | +| `--load` | | | Shorthand for `--output=type=docker` | +| `--metadata-file` | `string` | | Write build result metadata to a file | +| `--network` | `string` | `default` | Set the networking mode for the `RUN` instructions during build | +| `--no-cache` | | | Do not use cache when building the image | +| `--no-cache-filter` | `stringArray` | | Do not cache specified stages | +| `-o`, `--output` | `stringArray` | | Output destination (format: `type=local,dest=path`) | +| `--platform` | `stringArray` | | Set target platform for build | +| `--progress` | `string` | `auto` | Set type of progress output (`auto`, `plain`, `tty`, `rawjson`). Use plain to show container output | +| `--provenance` | `string` | | Shorthand for `--attest=type=provenance` | +| `--pull` | | | Always attempt to pull all referenced images | +| `--push` | | | Shorthand for `--output=type=registry` | +| `-q`, `--quiet` | | | Suppress the build output and print image ID on success | +| `--root` | `string` | | Specify root directory of server to connect (EXPERIMENTAL) | +| `--sbom` | `string` | | Shorthand for `--attest=type=sbom` | +| `--secret` | `stringArray` | | Secret to expose to the build (format: `id=mysecret[,src=/local/secret]`) | +| `--server-config` | `string` | | Specify buildx server config file (used only when launching new server) (EXPERIMENTAL) | +| `--shm-size` | `bytes` | `0` | Shared memory size for build containers | +| `--ssh` | `stringArray` | | SSH agent socket or keys to expose to the build (format: `default\|[=\|[,]]`) | +| `-t`, `--tag` | `stringArray` | | Name and optionally a tag (format: `name:tag`) | +| `--target` | `string` | | Set the target build stage to build | +| `--ulimit` | `ulimit` | | Ulimit options |