Install & Compatibility
Where this runs
tested against v1.4.39 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.940 runs
installs and imports cleanly · install 0.0s · import 2.521s · 165.3MB
glibcpy 3.10–3.940 runs
installs and imports cleanly · install 15.0s · import 2.339s · 159MB
168MB installed
● package 168MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Service
✓ from bentoml import Service
bentoml.io
✓ from bentoml.io import JSON, NumpyNdarray, Image # Or other I/O types
models.save
✓ import bentoml
bentoml.models.save(...)
✗ bentoml.pickler.save_model(...)
The `bentoml.pickler` module and direct `save_model` function was part of the 0.x API. In 1.x, use `bentoml.models.save` for model management.
bentoml.BentoService
✓ from bentoml import Service
✗ from bentoml import BentoService
The class for defining an ML service was renamed from `BentoService` to `Service` in the 1.0 release.
bentoml.artifacts
✓ import bentoml
# Access models via bentoml.models.get or by name in Service constructor
✗ from bentoml.adapters import DataframeInput
The `bentoml.artifacts` and `bentoml.adapters` modules were removed in the 1.0 release. Model loading is now handled via `bentoml.models.get` and I/O handling via `bentoml.io`.
This quickstart demonstrates how to define a `bentoml.Service`, save a dummy function as a 'model' using `bentoml.models.save`, and expose it via an API endpoint with `bentoml.io` for input/output handling. It shows how to serve it locally and interact with it via `curl`.
import bentoml
from bentoml.io import JSON
from pydantic import BaseModel
import os
# Define a Pydantic model for input data validation
class InputData(BaseModel):
name: str
age: int
# Define a simple prediction function to be served
def greeter_predict(input_data: InputData) -> dict:
return {"greeting": f"Hello, {input_data.name}! You are {input_data.age} years old."}
# Save a dummy 'greeter' model (in real apps, this would be a trained ML model)
# This model is essentially just the greeter_predict function itself for demonstration
# In a real scenario, you'd save a scikit-learn model, a PyTorch model, etc.
model_tag = bentoml.models.save(
name="greeter_model",
obj=greeter_predict, # Saving the function directly for this simple example
signatures={
"predict": {"batchable": False}
}
)
# Create a BentoML Service
# The 'models' argument tells BentoML which models this service depends on
svc = bentoml.Service(
name="greeter_service",
models=[model_tag] # Reference the saved model by its tag
)
# Define an API endpoint using the saved model
# The `input` and `output` decorators specify the data types for the API
@svc.api(input=JSON(pydantic_model=InputData), output=JSON())
async def greet(input_data: InputData) -> dict:
# Load the model from the BentoML model store
greeter_model = await bentoml.models.get(model_tag.name)
# Call the model's signature (in this case, our saved function)
result = greeter_model.predict(input_data)
return result
# To run this service locally:
# 1. Save the code above as `service.py`
# 2. Run in terminal: `bentoml serve service.py:svc --reload`
# 3. Access at http://localhost:3000/greet with a POST request, e.g.:
# curl -X POST -H "Content-Type: application/json" \
# -d '{"name": "Alice", "age": 30}' \
# http://localhost:3000/greet
bentoml --version
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'bentoml'
BentoML library is not installed in the active Python environment.
fixRun `pip install bentoml` to install the library.
bentoml.exceptions.NotFound: Model 'your_model_name:latest' not found
The BentoML service or build command cannot find the specified model in the local model store.
fixEnsure that `bentoml.models.save()` was executed successfully for 'your_model_name' and that the `bentoml.Service` constructor correctly references the model tag (e.g., `models=[bentoml.models.get('your_model_name')]`). Verify the model name and version are correct. TypeError: Object of type <PydanticModel> is not JSON serializable
You are trying to return a Pydantic model directly from an API endpoint declared with `output=JSON()` without proper serialization.
fixConvert the Pydantic model to a dictionary before returning it (e.g., `return my_pydantic_model.dict()`) or ensure your Pydantic model implements a `json()` method if you intended to use that directly.
RuntimeError: No event loop is running in current thread.
An asynchronous API endpoint (defined with `async def`) or an async operation is being called from a synchronous context or without a proper async event loop managed by AnyIO/asyncio.
fixEnsure you are using `await` for async calls within async functions. If calling sync code from async, or vice-versa, ensure correct thread management or consider using `anyio.to_thread.run_sync` for blocking operations within async APIs, or `asyncio.run` for running top-level async functions.
OperationalError: database is locked
Concurrent access attempts to the SQLite database used by BentoML for metadata storage, often occurring in high-concurrency scenarios or when `bentoml serve` is killed uncleanly.
fixThis issue is often mitigated in newer BentoML versions with increased SQLite busy timeout and WAL mode. Ensure you are on a recent version (>=1.4.36). If it persists, ensure only one process accesses the database at a time or consider using a persistent model store backend for production.
Upgrade
Version history
1.4.39latest on PyPI · released May 7, 2026
Audit
Dependencies
scikit-learnoptionalCommon ML framework used with BentoML for model serving. Installable via `pip install "bentoml[sklearn]"`.
torchoptionalPopular deep learning framework. Installable via `pip install "bentoml[pytorch]"`.
tensorflowoptionalPopular deep learning framework. Installable via `pip install "bentoml[tensorflow]"`.