buildx_build

Build an image with BuildKit via docker buildx build.

Replaces the legacy image_build tool when you need any of: multi-platform output (platforms), modern cache export (cache_from/cache_to), SBOM or provenance attestations, build secrets, or multi-stage builds with target. Always runs with --progress=plain so output is captured rather than redrawn on a TTY. With no local buildx plugin and an ssh:// target, the build runs on that host: a local context directory is copied there honouring .dockerignore, as are file, build_contexts and secret paths. Raises RuntimeError in that case for output/cache_to with a filesystem dest=, cache_from with a local src=, or any ssh= — each would resolve on the remote machine, losing the output or silently changing the build.

args: context - Build context: a filesystem path or Git/HTTP URL (verbatim; no ~/glob expansion). The - stdin-tarball form is NOT supported (stdin isn't forwarded — it'd block on the server's own stdin); serve a pre-packed tarball over HTTP instead. Copied to the target host when it names a local directory and there is no local plugin. tags - Image references to apply (-t, repeatable) platforms - Target platforms, e.g. ["linux/amd64", "linux/arm64"] file - Dockerfile path. A relative path resolves against this server's working directory (buildx's own rule), NOT against context — pass e.g. "ctx/Dockerfile" for a Dockerfile inside the context directory "ctx". build_args - Build-time variables (each becomes --build-arg KEY=VALUE) build_contexts - Additional named build contexts (e.g. {"deps": "./vendor"}) labels - Labels to set on the resulting image (each becomes --label KEY=VALUE) annotations - OCI manifest annotations (passed verbatim, repeatable) target - Target build stage to stop at push - Push the result to the registry (mutually exclusive with load) load - Load the result into the local image store (single-platform builds only) output - Custom --output specs (e.g. ["type=tar,dest=out.tar"]). A filesystem dest= is refused when the build has to run on a remote host; dest=- (stdout) is fine. no_cache - Do not use cache when building no_cache_filter - Stage names to exclude from caching pull - Always attempt to pull a newer version of each base image cache_from - Cache import specs, e.g. ["type=registry,ref=user/img:cache"] cache_to - Cache export specs builder - Override the active builder sbom - Shorthand for --attest=type=sbom; pass "true" or a config string provenance - Shorthand for --attest=type=provenance; pass "true", "false", or a config string attest - Custom attestation specs (repeatable) secret - Secret specs (e.g. ["id=npmrc,src=/home/user/.npmrc"] or ["id=npmrc,env=NPM_TOKEN"]). ~ in src= is NOT expanded (by this tool or the CLI) — use an absolute path. ssh - SSH agent socket/key specs (e.g. ["default"], using $SSH_AUTH_SOCK). Refused when the build has to run on a remote host: the socket read would be that host's. timeout_seconds - Subprocess timeout (default 1800s) returns: dict - {"returncode": int, "stdout": str, "stderr": str, "truncated": bool}