Implementation:Bentoml BentoML Podman Backend

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

Overview

Implements the Podman container builder backend for BentoML, extending the OCIBuilder base class to build OCI images using the Podman CLI with support for rootless builds and Buildah-compatible options.

Description

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

BUILDKIT_SUPPORT -- Set to False since Podman uses Buildah internally rather than Docker BuildKit.
ENV -- Reuses the Buildah environment variables (BUILDAH_FORMAT=oci, DOCKER_BUILDKIT=0).
find_binary() -- Locates the podman executable using shutil.which.
health() -- Checks that Podman is installed. On macOS and Windows, additionally verifies that the Podman machine is running by checking podman machine info for a "running" state.
construct_build_args() -- Builds the CLI argument list for podman build. Supports an extensive set of options:
- add_host -- Host-to-IP mappings (dict or tuple)
- all_platforms -- Build for all platforms (boolean flag)
- annotation -- Image annotations (dict or tuple)
- label -- Image labels (dict or tuple)
- build_arg -- Build-time variables (dict or tuple)
- build_context -- Additional build contexts (dict or tuple)
- creds -- Registry credentials (string or dict)
- decryption_key -- Decryption keys (string or dict)
- env -- Environment variables for the build (string or dict)
- output -- Custom output configuration (string or dict)
- runtime_flag -- Runtime flags (string or dict)
- secret -- Build secrets (string or dict)
- ulimit -- Resource limits (string or dict with (soft, hard) tuples)
- userns_gid_map -- User namespace GID mapping (string or (container, host, size) tuple)
- userns_uid_map -- User namespace UID mapping (string or (container, host, size) tuple)
- volume -- Volume mounts (string or (host, container, options) tuple)
- Additional keyword arguments are passed through with underscores replaced by hyphens.

Usage

Use this backend when building OCI container images with Podman, particularly in rootless, daemonless, or Docker-free container environments.

Code Reference

Source Location

Repository: Bentoml_BentoML
File: src/bentoml/_internal/container/podman.py
Lines: 1-133

Signature

BUILDKIT_SUPPORT = False

def find_binary() -> str | None: ...
def health() -> bool: ...
def construct_build_args(
    *,
    context_path: PathType = ".",
    add_host: dict[str, str] | ArgType = None,
    all_platforms: bool = False,
    annotation: dict[str, str] | ArgType = None,
    label: dict[str, str] | ArgType = None,
    build_arg: dict[str, str] | ArgType = None,
    build_context: dict[str, str] | ArgType = None,
    creds: str | dict[str, str] | ArgType = None,
    decryption_key: str | dict[str, str] | ArgType = None,
    env: str | dict[str, str] | ArgType = None,
    output: str | dict[str, str] | ArgType = None,
    runtime_flag: str | dict[str, str] | ArgType = None,
    secret: str | dict[str, str] | ArgType = None,
    ulimit: str | dict[str, tuple[int, int]] | ArgType = None,
    userns_gid_map: str | tuple[str, str, str] | None = None,
    userns_uid_map: str | tuple[str, str, str] | None = None,
    volume: str | tuple[str, str, str] | None = None,
    **kwargs: t.Any,
) -> Arguments: ...

Import

from bentoml._internal.container import podman

I/O Contract

Inputs

Name	Type	Required	Description
context_path	PathType	No	Build context directory (default: ".")
add_host	dict or tuple	No	Extra host-to-IP mappings
all_platforms	bool	No	Build for all platforms (default: False)
annotation	dict or tuple	No	Image annotations
build_arg	dict or tuple	No	Build-time variables
build_context	dict or tuple	No	Additional build contexts
creds	str or dict	No	Registry credentials
env	str or dict	No	Environment variables for the build
userns_gid_map	str or tuple	No	User namespace GID mapping
userns_uid_map	str or tuple	No	User namespace UID mapping
volume	str or tuple	No	Volume mount specification

Outputs

Name	Type	Description
Arguments	Arguments	Constructed CLI argument list for podman build command
bool	bool	Health check result (includes Podman machine status on macOS/Windows)
str or None	str or None	Path to podman binary (from find_binary)

Usage Examples

from bentoml._internal.container import podman

# Check if podman is available and running
if podman.health():
    # Construct build arguments
    args = podman.construct_build_args(
        context_path="/path/to/project",
        build_arg={"VERSION": "1.0", "ENV": "production"},
        label={"maintainer": "team@example.com"},
        annotation={"org.opencontainers.image.source": "https://github.com/example"},
        volume=("/host/path", "/container/path", "ro"),
        tag=("myimage:latest",),
    )

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment