buildx_build
Build container images with BuildKit, supporting multi-platform builds, cache import/export, attestations, build secrets, and multi-stage targets.
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.
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 ToolInputError 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.
Does not raise on a non-zero CLI exit (a missing buildx plugin or a timeout still raises) - inspect
returncode/stderr in the result.
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}
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 |