Skip to content

Ultralytics Models

SAHI integrates with Ultralytics YOLO26, Ultralytics YOLO11, and Ultralytics YOLOv8, along with all other Ultralytics model variants (detection, segmentation, and oriented bounding boxes).

sahi.models.ultralytics

Ultralytics detection model wrapper for SAHI.

Provides integration with Ultralytics YOLO models for object detection, instance segmentation, and oriented bounding box detection.

Classes

UltralyticsDetectionModel 

UltralyticsDetectionModel(
    *args: object,
    fuse: bool = False,
    task: str | None = None,
    **kwargs: object,
)

Bases: DetectionModel

Detection model for Ultralytics YOLO models.

Supports PyTorch (.pt), ONNX (.onnx), OpenVINO (.xml or _openvino_model/), NCNN (.param or _ncnn_model/), and TorchScript (.torchscript) models.

Initialize the Ultralytics detection model.

Accepts all arguments from DetectionModel.__init__ plus the following keyword arguments.

Parameters:

Name Type Description Default
*args
object

Variable length argument list passed to DetectionModel.

 ()
fuse
bool

If True, fuse Conv2d and BatchNorm2d layers for faster inference. Default: False.

 False
task
str | None

Ultralytics task type (e.g. "detect", "segment", "obb"). When None, the task is inferred from the model. Default: None.

 None
**kwargs
object

Arbitrary keyword arguments passed to DetectionModel.

 {}
Source code in sahi/models/ultralytics.py 
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
def __init__(self, *args: object, fuse: bool = False, task: str | None = None, **kwargs: object) -> None:
    """Initialize the Ultralytics detection model.

    Accepts all arguments from ``DetectionModel.__init__`` plus the
    following keyword arguments.

    Args:
        *args: Variable length argument list passed to DetectionModel.
        fuse: If True, fuse Conv2d and BatchNorm2d layers for faster
            inference. Default: False.
        task: Ultralytics task type (e.g. ``"detect"``, ``"segment"``,
            ``"obb"``). When None, the task is inferred from the model.
            Default: None.
        **kwargs: Arbitrary keyword arguments passed to DetectionModel.
    """
    self.fuse: bool = fuse
    self.task: str | None = task
    existing_packages = getattr(self, "required_packages", None) or []
    self.required_packages = [*list(existing_packages), "ultralytics"]
    super().__init__(*args, **kwargs)  # type: ignore[misc, arg-type]
Attributes
category_names property 
category_names: list

Returns the list of category names from the model.

Falls back to category_mapping values when model metadata is unavailable (e.g. ONNX models without embedded names).

Raises:

Type Description
ValueError

If neither model names nor category_mapping are available.
num_categories property 
num_categories: int

Returns number of categories.

has_mask property 
has_mask: bool

Returns if model output contains segmentation mask.

is_obb property 
is_obb: bool

Returns if model output contains oriented bounding boxes.

Methods:
load_model 
load_model() -> None

Detection model is initialized and set to self.model.

Source code in sahi/models/ultralytics.py 
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
def load_model(self) -> None:
    """Detection model is initialized and set to self.model."""
    from ultralytics import YOLO

    try:
        assert self.model_path is not None, "model_path must be provided for Ultralytics models"
        if self.task:
            model = YOLO(self.model_path, task=self.task)
        else:
            model = YOLO(self.model_path)

        # Only call .to(device) for PyTorch models, not ONNX,OpenVINO,Ncnn.
        if self.model_path and isinstance(self.model_path, str) and self.model_path.endswith(".pt"):
            model.to(self.device)
        self.set_model(model)
        if self.fuse and hasattr(model, "fuse"):
            model.fuse()

    except Exception as e:
        raise TypeError("model_path is not a valid Ultralytics model path: ", e)
set_model 
set_model(model: Any, **kwargs: Any) -> None

Sets the underlying Ultralytics model.

Parameters:

Name Type Description Default
model Any

Any A Ultralytics model

 required
**kwargs Any

Any Additional keyword arguments for model setup.

 {}
Source code in sahi/models/ultralytics.py 
70
71
72
73
74
75
76
77
78
79
80
81
82
83
def set_model(self, model: Any, **kwargs: Any) -> None:
    """Sets the underlying Ultralytics model.

    Args:
        model: Any
            A Ultralytics model
        **kwargs: Any
            Additional keyword arguments for model setup.
    """
    self.model = model
    # set category_mapping
    if not self.category_mapping:
        category_mapping = {str(ind): category_name for ind, category_name in enumerate(self.category_names)}
        self.category_mapping = category_mapping
perform_inference 
perform_inference(image: ndarray) -> None

Prediction is performed using self.model and the prediction result is set to self._original_predictions.

Parameters:

Name Type Description Default
image ndarray

np.ndarray A numpy array that contains the image to be predicted. 3 channel image should be in RGB order.

 required
Source code in sahi/models/ultralytics.py 
85
86
87
88
89
90
91
92
def perform_inference(self, image: np.ndarray) -> None:
    """Prediction is performed using self.model and the prediction result is set to self._original_predictions.

    Args:
        image: np.ndarray
            A numpy array that contains the image to be predicted. 3 channel image should be in RGB order.
    """
    self.perform_batch_inference([image])
perform_batch_inference 
perform_batch_inference(images: list[ndarray]) -> None

Performs inference on a batch of images using native YOLO batch support.

Parameters:

Name Type Description Default
images list[ndarray]

list[np.ndarray] List of numpy arrays (H, W, C) in RGB order.

 required
Source code in sahi/models/ultralytics.py 
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
def perform_batch_inference(self, images: list[np.ndarray]) -> None:
    """Performs inference on a batch of images using native YOLO batch support.

    Args:
        images: list[np.ndarray]
            List of numpy arrays (H, W, C) in RGB order.
    """
    if self.model is None:
        raise ValueError("Model is not loaded, load it by calling .load_model()")

    kwargs = {"cfg": self.config_path, "verbose": False, "conf": self.confidence_threshold, "device": self.device}

    if self.image_size is not None:
        kwargs = {"imgsz": self.image_size, **kwargs}

    # YOLO expects BGR -- convert each image and pass the list for native batch inference
    images_bgr = [img[:, :, ::-1] for img in images]
    prediction_result = self.model(images_bgr, **kwargs)

    self._original_predictions = self._extract_predictions(prediction_result)
    self._original_shapes = [img.shape for img in images]

Functions: