Implementation:Bentoml BentoML Image Builder
| Sources | Domains | Last Updated |
|---|---|---|
| BentoML, BentoML Containerization | ML_Serving, Containerization, Environment_Management | 2026-02-13 15:00 GMT |
Overview
The Image class provides a chainable builder API for declaratively specifying Docker runtime environments for BentoML services.
Description
Image is an attrs-based class that accumulates environment specifications (base image, Python packages, system packages, shell commands) through chainable methods. Each method returns Self, enabling fluent method chaining. The freeze() method compiles the accumulated configuration into an ImageInfo object used for Dockerfile generation during the Bento build process.
Usage
Instantiate an Image object, chain configuration methods, and reference it in a BentoML service definition or build configuration.
Code Reference
Source Location: Repository: bentoml/BentoML, File: src/_bentoml_sdk/images.py (L42-420)
Signature:
@attrs.define
class Image:
base_image: str = ""
distro: str = "debian"
python_version: str = DEFAULT_PYTHON_VERSION
commands: List[str] = []
lock_python_packages: bool = True
pack_git_packages: bool = True
python_requirements: str = ""
post_commands: List[str] = []
build_include_paths: List[str] = []
Import:
from bentoml import Image
Chainable Methods:
def python_packages(self, *packages: str) -> Self:
"""Add Python packages to the image."""
def system_packages(self, *packages: str) -> Self:
"""Add system packages (apt/apk) to the image."""
def run(self, command: str) -> Self:
"""Add a shell command to run during image build."""
def requirements_file(self, path: str) -> Self:
"""Add Python packages from a requirements.txt file."""
def build_include(self, *paths: str) -> Self:
"""Include additional files in the build context."""
I/O Contract
Inputs:
| Parameter | Type | Required | Description |
|---|---|---|---|
| base_image | str | No | Custom base Docker image (default: auto-selected based on distro) |
| distro | str | No | Linux distribution: "debian" or "alpine" (default debian) |
| python_version | str | No | Python version string (default: current interpreter version) |
| lock_python_packages | bool | No | Whether to lock Python package versions (default True) |
| pack_git_packages | bool | No | Whether to pack git-based packages into the image (default True) |
| python_requirements | str | No | Inline requirements string |
| commands | List[str] | No | Shell commands to run during build (pre-install) |
| post_commands | List[str] | No | Shell commands to run after package installation |
| build_include_paths | List[str] | No | Additional file paths to include in the build context |
Outputs:
- Image instance (from chainable methods) -- returns Self for method chaining
- ImageInfo (from freeze()) -- compiled environment specification for Dockerfile generation
Usage Examples
Example 1 -- Basic image with Python packages:
from bentoml import Image
image = Image(python_version="3.11").python_packages(
"torch>=2.0",
"transformers",
"accelerate",
)
Example 2 -- Image with system packages and custom commands:
from bentoml import Image
image = (
Image(distro="debian", python_version="3.11")
.system_packages("libgl1-mesa-glx", "libglib2.0-0")
.python_packages("opencv-python", "numpy")
.run("echo 'Build complete'")
)
Example 3 -- Image with requirements file and build includes:
from bentoml import Image
image = (
Image()
.requirements_file("requirements.txt")
.build_include("data/config.yaml", "scripts/setup.sh")
.run("bash scripts/setup.sh")
)