Environment:Bentoml BentoML Python Runtime

Knowledge Sources	BentoML PyPI BentoML
Domains	Infrastructure, ML_Serving
Last Updated	2026-02-13 16:00 GMT

Overview

Python 3.9+ runtime environment with core dependencies for running BentoML services, including HTTP/gRPC serving, telemetry, and container building.

Description

This environment defines the base Python runtime and package requirements for BentoML. It requires Python >= 3.9 (supporting 3.9, 3.10, 3.11, 3.12 on CPython). The core dependency stack includes Starlette/Uvicorn for HTTP serving, OpenTelemetry for distributed tracing, Prometheus for metrics, and PyYAML/Jinja2 for configuration templating. The build system uses Hatch with VCS-based versioning. The `uv` package manager is auto-installed if not present to handle dependency locking.

Usage

Use this environment for any BentoML workflow: defining services, building Bentos, serving models, or deploying to BentoCloud. This is the mandatory base environment for all BentoML operations.

System Requirements

Category	Requirement	Notes
OS	Linux, macOS, Windows	OS Independent per classifiers
Python	>= 3.9, CPython only	3.9, 3.10, 3.11, 3.12 tested
Disk	Varies	BENTOML_HOME defaults to ~/bentoml; stores bentos, models, envs

Dependencies

System Packages

`git` (for VCS-based versioning and git-lfs support)
`uv` (auto-installed if missing via pip)

Python Packages (Core)

`Jinja2` >= 3.0.1
`PyYAML` >= 5.0
`aiohttp`
`attrs` >= 22.2.0
`cattrs` >= 22.1.0, < 23.2.0
`kantoku` >= 0.18.3
`click` >= 7.0
`cloudpickle` >= 2.0.0
`httpx`
`numpy`
`nvidia-ml-py` (for GPU detection via pynvml)
`opentelemetry-api` ~= 1.20
`opentelemetry-sdk` ~= 1.20
`opentelemetry-instrumentation` ~= 0.41b0
`packaging` >= 22.0
`pip-requirements-parser` >= 31.2.0
`prometheus-client` >= 0.10.0
`psutil`
`pydantic` < 3
`rich` >= 11.2.0
`simple-di` >= 0.1.4
`starlette` >= 0.24.0
`uvicorn` >= 0.22.0
`watchfiles` >= 0.15.0
`fsspec` >= 2025.7.0
`tomli` >= 1.1.0 (Python < 3.11 only)

Python Packages (Optional Extras)

`bentoml[triton]`: `tritonclient` >= 2.29.0
`bentoml[grpc]`: `protobuf`, `grpcio`, `grpcio-health-checking`
`bentoml[io-image]`: `Pillow`
`bentoml[io-pandas]`: `pandas` >= 1, `pyarrow`
`bentoml[aws]`: `s3fs`
`bentoml[tracing]`: Jaeger, Zipkin, and OTLP exporters

Credentials

The following environment variables are used for configuration (not secrets):

`BENTOML_HOME`: Override default BentoML home directory (default: `~/bentoml`)
`BENTOML_CONFIG`: Path to a YAML config file for BentoML settings
`BENTOML_CONFIG_OVERRIDES`: JSON overrides for BentoML configuration
`BENTOML_DEBUG`: Set to `true` to enable debug logging
`BENTOML_QUIET`: Set to `true` to suppress output
`BENTOML_NO_LOCAL_URL`: Set to skip local URL resolution for editable installs
`BENTOML_CONTAINERIZED`: Set when running inside a container
`BENTOML_RESULT_STORE`: Override path for task result database

Quick Install

# Install BentoML with core dependencies
pip install bentoml

# Install with all optional extras
pip install "bentoml[all]"

# Install with specific extras
pip install "bentoml[triton,grpc,io-image,tracing]"

Code Evidence

Python version requirement from `pyproject.toml:5`:

requires-python = ">=3.9"

Auto-install of uv from `configuration/__init__.py:232-262`:

@lru_cache(maxsize=1)
def get_uv_command() -> list[str]:
    if uv := shutil.which("uv"):
        return [uv]
    try:
        importlib.metadata.version("uv")
    except importlib.metadata.PackageNotFoundError:
        install_cmd = [sys.executable, "-m", "pip", "install", "-q", "uv"]
        logger.info("uv is not installed, installing it with: %s", " ".join(install_cmd))
        subprocess.run(install_cmd, check=True, ...)
    return [sys.executable, "-m", "uv"]

Config file validation from `configuration/__init__.py:186-194`:

if bentoml_config_file:
    if not bentoml_config_file.endswith((".yml", ".yaml")):
        raise BentoMLConfigException(
            f"BentoML config file specified in ENV VAR does not end with '.yaml' or '.yml'"
        )
    if not os.path.isfile(bentoml_config_file):
        raise FileNotFoundError(
            f"BentoML config file specified in ENV VAR not found"
        )

Common Errors

Error Message	Cause	Solution
`BentoMLConfigException: Failed to install uv`	pip cannot install uv package	Install uv manually: `pip install uv` or `curl -LsSf https://astral.sh/uv/install.sh` then add to PATH
`BentoMLConfigException: Invalid configuration file`	Config YAML does not match schema	Validate config against `default_configuration.yaml`; check version field matches v1 or v2
`FileNotFoundError: BentoML config file specified in ENV VAR not found`	BENTOML_CONFIG points to missing file	Check the BENTOML_CONFIG path exists and is accessible

Compatibility Notes

Python 3.11+: Uses built-in `tomllib` instead of `tomli` for TOML parsing.
Windows: Supported but with caveats for gRPC production serving (requires `--development` mode). Reloader plugin output not shown due to circus limitations.
macOS/FreeBSD: gRPC production serving may behave incorrectly due to `SO_REUSEPORT` implementation differences. Containerize as Linux instead.
Default lock platform: When building on non-Linux or non-x86_64, packages are locked for `x86_64-manylinux_2_36` by default.

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment