Implementation:Bentoml BentoML Service Loader

Knowledge Sources	Bentoml_BentoML
Domains	Service Loading, Module Import, Bento Management
Last Updated	2026-02-13 15:00 GMT

Overview

The Service Loader module provides functions to import BentoML Service instances from Python source code or load them from built Bento artifacts, handling module resolution, working directory management, and model store configuration.

Description

This module contains the core service loading infrastructure for BentoML. It supports both legacy Service instances and new-style @bentoml.service() services (referred to as NewService). Key functions include:

import_service(svc_import_path, ...): The primary function for importing a service from source code.

• Path resolution: Accepts module paths in multiple formats: "module:attr", "module.py:attr", "module", "./path/to/module.py:attr".
• Working directory management: Temporarily modifies os.getcwd() and sys.path to the specified working directory, restoring them on completion (or on error).
• Model store injection: Temporarily sets a custom model store via BentoMLContainer.model_store.
• Cleanup via _restore(): An inner function that undoes changes to sys.path, cwd, and optionally the model store.

_do_import(svc_import_path, working_dir, reload): The internal import implementation.

• Module resolution: For file paths, converts to module names by walking up the directory tree to the working directory. For module names, uses them directly.
• Service discovery: If an attribute is specified (after :), traverses it on the module. Supports dotted attribute paths and traverses NewService dependencies.
• Auto-detection: When no attribute is specified, scans module globals for NewService instances (excluding dependents) or falls back to legacy Service instances. Requires exactly one service per module if no attribute is specified.
• Reload support: If the module is already in sys.modules and reload=True, calls importlib.reload().

load_bento(bento, reload, standalone_build): Loads a service from a Bento artifact in the local bento store.

• Validates BentoML version compatibility between the Bento and current runtime.
• Delegates to _load_bento for actual loading.

_load_bento(bento, reload, standalone_build): Internal Bento loading.

• Sets up arguments from bento.info.args.
• Configures the model store to use the Bento's local model store if available.
• Resolves model aliases from the Bento's model metadata.
• Calls import_service with the Bento's project directory as working directory.
• Invokes svc.on_load_bento(bento) to finalize service configuration.

load_bento_dir(path, ...): Loads from a Bento directory path.

load(bento_identifier, ...): The unified entry point that determines whether the identifier is a Bento tag, Bento directory path, or an import string, and dispatches accordingly. It checks for bento.yaml, bentofile.yaml, and service.py in directories, falling through multiple loading strategies.

Usage

Used throughout BentoML's CLI and server infrastructure to load services for serving, building, and testing. The load function is the primary public API, invoked by bentoml serve and related commands.

Code Reference

Source Location

• Repository: Bentoml_BentoML
• File: src/bentoml/_internal/service/loader.py
• Lines: 1-437

Signature

@inject
def import_service(
    svc_import_path: str,
    *,
    working_dir: t.Optional[str] = None,
    reload: bool = False,
    standalone_load: bool = False,
    model_store: ModelStore = Provide[BentoMLContainer.model_store],
) -> AnyService: ...

def _do_import(
    svc_import_path: str,
    working_dir: str,
    reload: bool = False,
) -> AnyService: ...

@inject
def load_bento(
    bento: str | Tag | Bento,
    reload: bool = False,
    standalone_build: bool = False,
    bento_store: "BentoStore" = Provide[BentoMLContainer.bento_store],
) -> AnyService: ...

def load_bento_dir(
    path: str,
    reload: bool = False,
    standalone_build: bool = False,
) -> AnyService: ...

def load(
    bento_identifier: str | Tag | Bento,
    working_dir: t.Optional[str] = None,
    reload: bool = False,
    standalone_load: bool = False,
) -> AnyService: ...

Import

from bentoml._internal.service.loader import load
from bentoml._internal.service.loader import import_service
from bentoml._internal.service.loader import load_bento

I/O Contract

Inputs

Name	Type	Required	Description
bento_identifier	str, Tag, or Bento	Yes	Service import path (e.g., "module:svc"), Bento tag (e.g., "MyService:latest"), or Bento object.
working_dir	str or None	No	Working directory for module imports. Defaults to current directory.
reload	bool	No	Whether to reload already-imported modules. Defaults to False.
standalone_load	bool	No	If True, persists changes to cwd and model store. Defaults to False.

Outputs

Name	Type	Description
AnyService	Service or NewService	The loaded or imported BentoML service instance (legacy or new-style).

Usage Examples

from bentoml._internal.service.loader import load, import_service

# Load from a module import path
svc = import_service("fraud_detector:svc")

# Load from a file path
svc = import_service("fraud_detector.py:svc", working_dir="/path/to/project")

# Auto-detect the service in a module (single service per module)
svc = import_service("fraud_detector")

# Load from local bento store by tag
svc = load("FraudDetector:latest")

# Load from a bento directory
svc = load("~/bentoml/bentos/iris_classifier/4tht2icroji6zput")

# Load from source with working directory
svc = load("service.py:svc", working_dir="/path/to/project")

Related Pages

• Implementation:Bentoml_BentoML_Legacy_Service
• Implementation:Bentoml_BentoML_Runner_Class