buildx_build
Build Docker images with BuildKit, supporting multi-platform outputs, cache import/export, and advanced features like attestations and build secrets.
Instructions
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.
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.
tags - Image references to apply (-t, repeatable)
platforms - Target platforms, e.g. ["linux/amd64", "linux/arm64"]
file - Dockerfile path (relative to context unless absolute)
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"])
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)
timeout_seconds - Subprocess timeout (default 1800s)
returns: dict - {"returncode": int, "stdout": str, "stderr": str, "truncated": bool}
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ssh | No | ||
| file | No | ||
| load | No | ||
| pull | No | ||
| push | No | ||
| sbom | No | ||
| tags | No | ||
| attest | No | ||
| labels | No | ||
| output | No | ||
| secret | No | ||
| target | No | ||
| builder | No | ||
| context | Yes | ||
| cache_to | No | ||
| no_cache | No | ||
| platforms | No | ||
| build_args | No | ||
| cache_from | No | ||
| provenance | No | ||
| annotations | No | ||
| build_contexts | No | ||
| no_cache_filter | No | ||
| timeout_seconds | No |