---
schema_version: 1
route: /t/buildkit.md
tool: "buildkit"
---

# sincecutoff.com /t/buildkit — BuildKit

- name: BuildKit
- kind: runtime
- children: none
- homepage: <https://github.com/moby/buildkit>

Changes to the tools coding agents drive, since a model's training cutoff, each linked to its first-party source. Check installed versions and limitations before acting; a cutoff date does not establish what a model knows.
Original editorial content: [Apache 2.0](https://sincecutoff.com/v1/data-license.txt), by [0xPatrick](https://0xpatrick.dev). Preserve applicable license and [NOTICE](https://sincecutoff.com/notice.txt) attribution when redistributing. Third-party source text and examples retain their own rights. [License scope and attribution](https://sincecutoff.com/v1/license.json).
To stay current, read the changes feed: [`/v1/changes.md?tool=buildkit`](https://sincecutoff.com/v1/changes.md?tool=buildkit) (or `.json`), adding `since=YYYY-MM-DD` for your training cutoff. Entries for registered children are included; the registry itself is `/v1/tools.json`. How to page and save your place: [llms.txt](https://sincecutoff.com/llms.txt).

### BuildKit local and tar exporters accept src (2026-10-07)
- slug: buildkit-local-and-tar-exporters-accept-src-ae98ec72a7ee
- score: 0.96

How to use it:

When exporting a build result with the local or tar exporter, set `src` to the subdirectory to export; it must point to a directory within the build result.

Examples:

```
buildctl build ... --output type=local,dest=<output-dir>,src=<build-result-subdirectory>
```

```
buildctl build ... --output type=tar,dest=<output.tar>,src=<build-result-subdirectory>
```

- why_it_matters: Export a selected subdirectory from a build result with the local or tar exporter.
- sources: <https://github.com/moby/buildkit/releases/tag/v0.34.0>, <https://github.com/moby/buildkit/blob/v0.34.0/README.md>
- gotchas: "Version: v0.34.0"; "--output type=local (required): Select the local exporter; `dest` names its destination directory."; "--output type=tar (required): Select the tar exporter; `dest` names its tarball destination. Tar output may also be sent to stdout."; "src: Exporter option: path to a directory in the build result. It is resolved from the result root; relative and absolute forms are equivalent. Its contents go to the destination root. Omitting it exports the entire filesystem."; "dest: Exporter option: destination directory or tarball path. The documented tar example also supports stdout without `dest`."; "Prerequisite: Use a BuildKit daemon that supports `src`; older daemons may ignore the option and export the entire build result."; "The `src` option applies to local and tar exporters."

### BuildKitd config path accepts BUILDKITD_CONFIG (2026-10-07)
- slug: buildkitd-config-path-accepts-buildkitd-config-1486d27401c6
- score: 0.96

How to use it:

When CI cannot inject command-line arguments, set `BUILDKITD_CONFIG` to the config file path and start `buildkitd`. An explicit `--config` flag takes precedence; if neither is set, the default path applies.

Examples:

```
BUILDKITD_CONFIG=/etc/buildkit/custom.toml buildkitd
```

- why_it_matters: Point BuildKitd at a custom configuration file in a restricted CI environment where injecting command-line arguments is not practical.
- sources: <https://github.com/moby/buildkit/releases/tag/v0.34.0>, <https://github.com/moby/buildkit/pull/7144>, <https://github.com/moby/buildkit/blob/v0.34.0/docs/buildkitd.toml.md>
- gotchas: "Version: v0.34.0"; "BUILDKITD_CONFIG: Environment variable containing only the configuration file path."; "--config <path>: Selects a different configuration file path; takes precedence over BUILDKITD_CONFIG."; "The environment variable contains only the config file path."; "An explicit `--config` flag takes precedence over the environment variable."; "The default path is unchanged when neither the flag nor variable is set."

### Dockerfile archives support zstd build contexts and ADD (2026-09-02)
- slug: dockerfile-archives-support-zstd-build-contexts-and-add-7770d6830eb0
- score: 0.97

How to use it:

When building with Dockerfile syntax 1.27.0, a zstd-compressed archive can be the build context or an `ADD` source. Use the archive as the context, or add its files with `ADD <archive> <destination>`; local tar archives unpack by default.

Examples:

```
# syntax=docker.io/docker/dockerfile-upstream:1.27.0
FROM alpine
ADD <archive.tar.zst> /destination/
```

```
docker build -f <Dockerfile> <context.tar.zst>
```

- why_it_matters: Build an image from a zstd-compressed archive or add files from one with Dockerfile instructions.
- sources: <https://github.com/moby/buildkit/releases/tag/dockerfile/1.27.0>, <https://github.com/moby/buildkit/blob/dockerfile/1.27.0/frontend/dockerfile/docs/reference.md>
- gotchas: "Version: dockerfile/1.27.0"; "<archive.tar.zst> (required): The local archive source; recognized compression is determined from file contents, not its filename."; "<destination> (required): Image path where `ADD` extracts the archive contents."; "--unpack=<bool>: Controls automatic archive extraction. Local tar archives unpack by default; no mutually exclusive object subkeys apply."; "Dockerfile syntax version (required): Use `docker/dockerfile-upstream:1.27.0` to select the release's Dockerfile frontend."; "Prerequisite: Use Dockerfile syntax `docker/dockerfile-upstream:1.27.0` or a frontend that supports the change."

### BuildKit exec steps can route network traffic through an HTTP proxy (2026-06-17)
- slug: buildkit-exec-steps-can-route-network-traffic-through-an-http-proxy-07cc6cf32dd2
- score: 0.98

How to use it:

When you need to inspect exec-step network requests or apply source policies to them, enable BuildKit proxy networking for the daemon or build, then review the build output. Use a source policy to allow, deny, or convert matching proxy-visible HTTP(S) GET URLs.

Examples:

```
buildctl build --proxy-network --frontend dockerfile.v0 --local context=<context-dir> --local dockerfile=<dockerfile-dir>
```

```
buildkitd --proxy-network
```

```
buildctl build --proxy-network --source-policy-file <policy.json> --frontend dockerfile.v0 --local context=<context-dir> --local dockerfile=<dockerfile-dir>
```

- why_it_matters: Inspect or constrain network requests made by containers during a build.
- sources: <https://github.com/moby/buildkit/releases/tag/v0.31.0>, <https://github.com/moby/buildkit/blob/v0.31.0/docs/proxy.md>, <https://github.com/moby/buildkit/blob/v0.31.0/docs/build-repro.md>
- gotchas: "Version: v0.31.0"; "--proxy-network: Enables proxy networking for the build; daemon-level `buildkitd --proxy-network` or `proxyNetwork = true` in `buildkitd.toml` also enables it."; "--source-policy-file <policy.json>: Loads source-policy rules from the named file; the policy can allow, deny, or convert matching proxy-visible HTTP(S) GET URLs."; "proxyNetwork: Daemon config boolean; set `true` to enable proxy networking by default."; "rules[].action (required): Documented policy example uses `CONVERT`; proxy policy can also allow or deny matching requests."; "rules[].selector.identifier (required): Selects a source by identifier; policy examples match identifiers such as HTTP URLs and docker-image references."; "rules[].updates.identifier: Replacement identifier for a `CONVERT` policy rule; the example pins an image reference to a digest."; "rules[].updates.attrs: Attributes to update for a `CONVERT` policy rule; the example sets `http.checksum`."; "Prerequisite: Proxy networking applies to exec traffic with network access; non-exec fetch paths are outside its scope."; "Prerequisite: For `RUN --network=host`, enable `network.host` on both daemon (`--allow-insecure-entitlement network.host`) and build request (`--allow network.host`)."; "Prerequisite: This implementation is Linux-focused."; "The proxy applies to exec steps; the release does not provide enablement syntax or configuration details."

### Local exporter supports mode=delete for build results (2026-06-17)
- slug: local-exporter-supports-mode-delete-for-build-results-a645d48896b2
- score: 0.97

How to use it:

When exporting a build result to a local directory that should match the result, use `mode=delete` to remove destination files and directories absent from the result.

Examples:

```
buildctl build ... --output type=local,dest=./bin/release,mode=delete
```

- why_it_matters: Export a build result to a local directory that must match the result and remain confined to that destination if it is mutated during transfer.
- before: Use the default `mode=copy`, which preserves existing destination files absent from the exported result.
- sources: <https://github.com/moby/buildkit/releases/tag/v0.31.0>, <https://github.com/moby/buildkit/pull/6561>, <https://github.com/moby/buildkit/blob/v0.31.0/README.md>
- gotchas: "Version: v0.31.0"; "type (required): Set to `local` for local directory output."; "dest (required): Destination directory for the local output."; "mode: `delete` removes destination files and directories absent from the result; `copy` is the default and preserves them. The documented values are alternatives."; "The default behavior remains mode=copy."; "For multi-platform local exports in delete mode, the complete export is sent as one filesystem; when platform splitting is enabled, a single platform-directory filesystem is built before streaming."

### Dockerfile SOURCE_DATE_EPOCH context and stage values (2026-05-13)
- slug: dockerfile-source-date-epoch-context-and-stage-values-cc3f7b4de5eb
- score: 0.94

How to use it:

When building with a remote context or a stage timestamp, define `ARG SOURCE_DATE_EPOCH=context` or `ARG SOURCE_DATE_EPOCH=<stage>` to set the build timestamp from that source. Context resolution uses the Git commit time or, for HTTP contexts, `Last-Modified` or the newest TAR entry mtime when the header is absent.

Examples:

```
ARG SOURCE_DATE_EPOCH=context
FROM alpine
```

```
ARG SOURCE_DATE_EPOCH=<stage>
FROM alpine
```

- why_it_matters: Set reproducible build timestamps from a remote context or build stage.
- sources: <https://github.com/moby/buildkit/releases/tag/dockerfile/1.24.0>, <https://github.com/moby/buildkit/blob/dockerfile/1.24.0/docs/build-repro.md>
- gotchas: "Version: dockerfile/1.24.0"; "SOURCE_DATE_EPOCH=context: Special build-arg value: resolve the main build context to a numeric Unix timestamp. Git context uses commit time; HTTP context uses `Last-Modified` or, for an archive without that header, the newest archive entry mtime."; "SOURCE_DATE_EPOCH=<stage>: Special build-arg value that selects the timestamp associated with the named stage."; "Prerequisite: Dockerfile frontend supports `SOURCE_DATE_EPOCH` as a special build arg since BuildKit 0.11; minimal support is available on older BuildKit with Dockerfile 1.5 frontend."; "The context timestamp is a Git commit timestamp for Git commit builds."; "For remote URL builds, the timestamp comes from TAR archive file metadata or the URL's `Last-Modified` header."; "Docs conflict: Release note says remote URL timestamps may come from TAR file metadata or `Last-Modified`; versioned build-repro docs specify the newest archive entry mtime when `Last-Modified` is absent."

### Git build contexts accept mtime=commit (2026-03-31)
- slug: git-build-contexts-accept-mtime-commit-9ceb2f6c551f
- score: 0.93

How to use it:

For a remote build with a Git context, add `mtime=commit` to the Git URL query to set snapshot file, symlink, and directory mtimes to the resolved commit timestamp. If the Dockerfile frontend receives `SOURCE_DATE_EPOCH`, commit-time mtimes are selected automatically; the URL parameter can override the policy.

Examples:

```
docker buildx build 'https://github.com/<owner>/<repo>.git?mtime=commit'
```

- why_it_matters: Make a remote build using a Git context reproducible by setting checked-out file timestamps to the commit time.
- sources: <https://github.com/moby/buildkit/releases/tag/dockerfile/1.23.0>, <https://github.com/moby/buildkit/pull/6600>
- gotchas: "Version: dockerfile/1.23.0"; "mtime: Git URL query parameter; `commit` selects resolved-commit mtimes. The documented alternatives are `commit` and `checkout`; the URL parameter can override the automatic policy."; "SOURCE_DATE_EPOCH: When set in the Dockerfile frontend, Git contexts automatically use commit-time mtimes. The docs do not specify a required value for this behavior."; "The automatic default applies to remote builds using a Git context that define `SOURCE_DATE_EPOCH`."

### LLB adds image registry and OCI layout raw blob sources (2026-03-04)
- slug: llb-adds-image-registry-and-oci-layout-raw-blob-sources-271bc78842e1
- score: 0.94

How to use it:

When an LLB definition needs one raw blob from a container image registry or OCI layout, use the matching blob source. It downloads the blob as a single file into an empty snapshot.

Examples:

```
blob := llb.ImageBlob("<registry>/<repository>@sha256:<digest>", llb.Filename("<filename>"))
```

```
blob := llb.OCILayoutBlob("<repository>@sha256:<digest>", llb.ImageBlobOCIStore("", "<store-id>"), llb.Filename("<filename>"))
```

- why_it_matters: Define an LLB source that reads a raw blob from an image registry or OCI layout.
- sources: <https://github.com/moby/buildkit/releases/tag/v0.28.0>, <https://github.com/moby/buildkit/pull/4286/files>
- gotchas: "Version: v0.28.0"; "reference (required): Blob reference in the form <registry>/<repository>@sha256:<digest> for a registry source, or <repository>@sha256:<digest> for an OCI layout source."; "llb.Filename(\"<filename>\"): Sets the downloaded blob's filename."; "llb.ImageBlobOCIStore(\"\", \"<store-id>\") (required): Selects the OCI layout content store by ID for the OCI layout source."; "Prerequisite: The source types were added in BuildKit v0.28.0."; "Prerequisite: For OCI layout sources, register the OCI content store in the LLB solve options using the same store ID."