Implementation:Bentoml BentoML BuildKit Backend

Knowledge Sources	Bentoml_BentoML
Domains	Container, OCI
Last Updated	2026-02-13 15:00 GMT

Overview

Implements the BuildKit (buildctl) container builder backend for BentoML, extending the OCIBuilder base class to build OCI images using the buildctl CLI with a buildkitd daemon.

Description

The buildctl module provides the BuildKit backend implementation for BentoML's container build system. It extends the OCIBuilder base class and exports the standard backend interface:

• BUILDKIT_SUPPORT -- Set to True as this is a native BuildKit client.
• find_binary() -- Locates the buildctl executable using shutil.which.
• buildkitd_health() -- Verifies that either buildkitd is installed or the BUILDKIT_HOST environment variable is set. If neither is available, it provides instructions for running a portable buildkitd container via Docker or Podman.
• health() -- Checks that the system is not Windows (buildctl is unsupported), buildkitd is healthy, and the buildctl binary is found.
• construct_build_args() -- Builds the CLI argument list for buildctl build. The argument construction is more complex than other backends because buildctl uses a different CLI structure:
  • --local arguments specify context and dockerfile directories
  • --frontend specifies the build frontend (default: "dockerfile.v0", alternative: "gateway.v0")
  • --output specifies the output format and destination
  • --opt passes frontend-specific options
  • Arguments are categorized using a regex pattern (is_ctl_arg) that matches buildctl-specific flags: output, progress, trace, local, frontend, opt, no-cache, export-cache, import-cache, secret, allow, ssh, metadata-file.
  • If tag is provided without explicit output, auto-configures Docker or OCI output format based on available tooling.

Usage

Use this backend when building container images with BuildKit for advanced caching, multi-stage builds, and parallel build execution capabilities.

Code Reference

Source Location

• Repository: Bentoml_BentoML
• File: src/bentoml/_internal/container/buildctl.py
• Lines: 1-178

Signature

BUILDKIT_SUPPORT = True

def find_binary() -> str | None: ...
def buildkitd_health() -> bool: ...
def health() -> bool: ...
def construct_build_args(
    *,
    file: PathType | None = None,
    tag: tuple[str] | None = None,
    context_path: PathType = ".",
    output: str | dict[str, str] | ArgType = None,
    **kwargs: t.Any,
) -> Arguments: ...

Import

from bentoml._internal.container import buildctl

I/O Contract

Inputs

Name	Type	Required	Description
context_path	PathType	No	Build context directory (default: ".")
file	PathType or None	No	Path to the Dockerfile
tag	tuple[str] or None	No	Image tag(s) for the output
output	str or dict or tuple	No	Output configuration (type, destination)
**kwargs	Any	No	Additional buildctl or frontend options

Outputs

Name	Type	Description
Arguments	Arguments	Constructed CLI argument list for buildctl build command
bool	bool	Health check result (from health or buildkitd_health)
str or None	str or None	Path to buildctl binary (from find_binary)

Usage Examples

from bentoml._internal.container import buildctl

# Check if buildctl and buildkitd are available
if buildctl.health():
    # Construct build arguments
    args = buildctl.construct_build_args(
        context_path="/path/to/project",
        file="/path/to/project/Dockerfile",
        tag=("myimage:latest",),
        output={"type": "docker", "name": "myimage:latest"},
    )

Related Pages

• Implementation:Bentoml_BentoML_OCIBuilder_Base
• Implementation:Bentoml_BentoML_Nerdctl_Backend