Implementation:Bentoml BentoML Nerdctl Backend

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

Overview

Implements the nerdctl container builder backend for BentoML, extending the OCIBuilder base class to build OCI images using the nerdctl CLI with containerd and BuildKit.

Description

The nerdctl module provides the nerdctl 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 since nerdctl relies on BuildKit for image builds.
• find_binary() -- Locates the nerdctl executable using shutil.which.
• health() -- Performs several checks:
  • Rejects Windows (nerdctl is not supported).
  • Warns if DOCKER_BUILDKIT is set (it has no effect with nerdctl).
  • Verifies nerdctl binary is found; provides platform-specific instructions (lima for macOS, BuildKit docs for Linux).
  • Delegates to buildctl.buildkitd_health() to verify BuildKit daemon availability.
• construct_build_args() -- Builds the CLI argument list for nerdctl build. Supports the following options:
  • build_arg -- Build-time variables (dict or tuple)
  • cache_from -- Cache import source (string or dict)
  • cache_to -- Cache export destination (string or dict)
  • label -- Image labels (dict or tuple)
  • output -- Custom output configuration (string or dict)
  • secret -- Build secrets (string or dict)
  • Additional keyword arguments are passed through with underscores replaced by hyphens.

The parse_dict_opt helper formats dictionaries into comma-separated key=value strings.

Usage

Use this backend when building container images with nerdctl, particularly in containerd-native environments or on Linux systems using BuildKit without Docker.

Code Reference

Source Location

• Repository: Bentoml_BentoML
• File: src/bentoml/_internal/container/nerdctl.py
• Lines: 1-99

Signature

BUILDKIT_SUPPORT = True

def find_binary() -> str | None: ...
def health() -> bool: ...
def construct_build_args(
    *,
    context_path: PathType = ".",
    build_arg: dict[str, str] | ArgType = None,
    cache_from: str | dict[str, str] | ArgType = None,
    cache_to: str | dict[str, str] | ArgType = None,
    label: dict[str, str] | ArgType = None,
    output: str | dict[str, str] | ArgType = None,
    secret: str | dict[str, str] | ArgType = None,
    **kwargs: t.Any,
) -> Arguments: ...

Import

from bentoml._internal.container import nerdctl

I/O Contract

Inputs

Name	Type	Required	Description
context_path	PathType	No	Build context directory (default: ".")
build_arg	dict or tuple	No	Build-time variables
cache_from	str or dict	No	Cache import source
cache_to	str or dict	No	Cache export destination
label	dict or tuple	No	Image labels
output	str or dict	No	Output configuration
secret	str or dict	No	Build secrets

Outputs

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

Usage Examples

from bentoml._internal.container import nerdctl

# Check if nerdctl and BuildKit are available
if nerdctl.health():
    # Construct build arguments
    args = nerdctl.construct_build_args(
        context_path="/path/to/project",
        build_arg={"VERSION": "1.0"},
        label={"maintainer": "team@example.com"},
        cache_from={"type": "registry", "ref": "myrepo/cache"},
        tag=("myimage:latest",),
    )

Related Pages

• Implementation:Bentoml_BentoML_OCIBuilder_Base
• Implementation:Bentoml_BentoML_BuildKit_Backend