Environment:Obss Sahi Python Detection Frameworks

Knowledge Sources	obss/sahi pyproject.toml
Domains	Computer_Vision, Object_Detection, Infrastructure
Last Updated	2026-02-08 12:00 GMT

Overview

Python 3.8+ environment with PyTorch >= 2.4.1 and optional detection framework backends (Ultralytics, Detectron2, MMDetection, HuggingFace Transformers, YOLOv5, TorchVision, Roboflow).

Description

This environment provides the runtime context for SAHI's detection model abstraction layer. SAHI supports multiple detection framework backends through a plugin architecture defined in `sahi/models/`. Each backend has its own required packages declared via the `required_packages` class attribute on its `DetectionModel` subclass. The `check_dependencies()` method on the base class validates that required packages are installed before model loading.

The core framework requires only PyTorch >= 2.4.1. Individual detection backends are optional dependencies — only the backend actually being used needs to be installed. SAHI uses lazy import checking via `sahi/utils/import_utils.py` to detect availability at runtime.

Usage

Use this environment for any workflow that performs object detection inference through SAHI. This is the mandatory prerequisite for running the AutoDetectionModel.from_pretrained() factory, get_prediction(), get_sliced_prediction(), and get_prediction() on full images. The specific optional packages required depend on which detection backend is selected via the `model_type` parameter.

System Requirements

Category	Requirement	Notes
OS	Linux, macOS, Windows	All platforms supported; MMDetection restricted to non-macOS-ARM64
Hardware	CPU or NVIDIA GPU	GPU optional but recommended; device auto-selected (CUDA > MPS > CPU)
Python	>= 3.8, <= 3.13	MMDetection only on 3.11; Roboflow only on >= 3.12; Transformers on >= 3.9
Disk	~2GB+	Varies by model weights downloaded

Dependencies

Core Packages (Always Required)

`torch` >= 2.4.1
`opencv-python` <= 4.11.0.86
`shapely` >= 2.0.0
`tqdm` >= 4.48.2
`pybboxes` == 0.1.6
`pillow` >= 8.2.0
`pyyaml`
`fire`
`requests`
`click`
`terminaltables`

Optional Backend Packages

Ultralytics (YOLOv8/v11): `ultralytics` >= 8.0.0
YOLOv5: `yolov5` >= 6.0.0, < 8.0.0
HuggingFace: `transformers` >= 4.49.0 (Python >= 3.9 only)
Detectron2: `detectron2` + `torch`
MMDetection: `mmdet` == 3.3.0, `mmcv` == 2.1.0, `mmengine` (Python == 3.11, not macOS ARM64), `numpy` < 2.0
TorchVision: `torchvision` (>= 0.13 for `weights` parameter)
Roboflow Universe: `inference` >= 0.51.5 (Python >= 3.12)
RFDETR: `rfdetr` >= 1.1.0 (Python >= 3.12)
ONNX export: `onnx`, `onnxruntime` (Python >= 3.10)

Credentials

The following environment variables may be needed depending on the backend:

`HF_TOKEN`: HuggingFace API token for accessing private or gated models (used in `sahi/models/huggingface.py`).
`ROBOFLOW_API_KEY`: Roboflow API key for Roboflow Universe model access (used in `sahi/models/roboflow.py`).
`CUDA_VISIBLE_DEVICES`: Set automatically by `select_device()` to control GPU allocation (used in `sahi/utils/torch_utils.py`).
`SAHI_DEBUG`: Set to any value to enable debug-level logging (used in `sahi/logger.py`).

Quick Install

# Core SAHI (CPU-only)
pip install sahi

# With specific backends
pip install "sahi[ultralytics]"     # Ultralytics YOLOv8/v11
pip install "sahi[yolov5]"          # YOLOv5
pip install "sahi[transformers]"    # HuggingFace
pip install "sahi[roboflow]"        # Roboflow + RFDETR
pip install "sahi[mmdet]"           # MMDetection (Python 3.11 only)
pip install "sahi[onnx]"            # ONNX export support

# All backends at once
pip install "sahi[all]"

Code Evidence

Lazy import checking from `sahi/utils/import_utils.py:47-58`:

def is_available(module_name: str):
    return importlib.util.find_spec(module_name) is not None

def check_requirements(package_names):
    """Raise error if module is not installed."""
    missing_packages = []
    for package_name in package_names:
        if importlib.util.find_spec(package_name) is None:
            missing_packages.append(package_name)
    if missing_packages:
        raise ImportError(f"The following packages are required to use this module: {missing_packages}")
    yield

Base model dependency enforcement from `sahi/models/base.py:55-60`:

class DetectionModel:
    required_packages: list[str] | None = None

    def check_dependencies(self, packages: list[str] | None = None) -> None:
        pkgs = packages if packages is not None else getattr(self, "required_packages", [])
        if pkgs:
            check_requirements(pkgs)

HuggingFace minimum version enforcement from `sahi/models/huggingface.py:36`:

ensure_package_minimum_version("transformers", "4.42.0")

Device auto-selection from `sahi/utils/torch_utils.py:50-85`:

def select_device(device: str | None = None) -> torch.device:
    # Order of preference: cuda:0 > mps > cpu
    if not cpu and not mps and torch.cuda.is_available() and valid_cuda_id:
        arg = f"cuda:{device}" if device else "cuda:0"
    elif mps and getattr(torch, "has_mps", False) and torch.backends.mps.is_available():
        arg = "mps"
    else:
        arg = "cpu"
    return torch.device(arg)

Supported model types from `sahi/auto_model.py:7-20`:

MODEL_TYPE_TO_MODEL_CLASS_NAME = {
    "ultralytics": "UltralyticsDetectionModel",
    "rtdetr": "RTDetrDetectionModel",
    "mmdet": "MmdetDetectionModel",
    "yolov5": "Yolov5DetectionModel",
    "detectron2": "Detectron2DetectionModel",
    "huggingface": "HuggingfaceDetectionModel",
    "torchvision": "TorchVisionDetectionModel",
    "roboflow": "RoboflowDetectionModel",
    "yolo-world": "YOLOWORLDDetectionModel",
    "yoloe": "YOLOEDetectionModel",
}

Common Errors

Error Message	Cause	Solution
`ImportError: The following packages are required to use this module: ['ultralytics']`	Backend package not installed	`pip install ultralytics` (or relevant backend)
`ImportError: Please upgrade transformers to version 4.42.0 or higher`	Transformers version too old	`pip install --upgrade transformers>=4.49.0`
`ValueError: Authorization failed. Please pass a valid API key...`	Missing Roboflow API key	Set `ROBOFLOW_API_KEY` environment variable or pass `api_key` parameter
`ModuleNotFoundError: Please run "pip install lsnms>0.3.1"`	LSNMS postprocess selected but package not installed	`pip install lsnms` (or use default GREEDYNMM instead)

Compatibility Notes

MMDetection: Only works with Python == 3.11 and not on macOS ARM64 (`platform_system != 'Darwin' or platform_machine != 'arm64'`). Requires `numpy` < 2.0 due to torch 2.1.2 incompatibility.
Roboflow/RFDETR: Requires Python >= 3.12.
HuggingFace Transformers: Requires Python >= 3.9.
ONNX: Requires Python >= 3.10.
YOLOv5: Version >= 6.2.0 changes the `model.names` API from list to dict (handled by version check in `sahi/models/yolov5.py:80`).
Device Selection: Automatically prefers CUDA > MPS (Apple Silicon) > CPU. Explicit device can be set via `device` parameter.
FiftyOne: Platform-specific MongoDB cleanup — uses `tskill mongod` on Windows, `pkill mongod` on Unix.

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment