> This is the documentation for LibreYOLO 1.6.0. Current version: https://www.libreyolo.com/docs/reference/python-api

# Python API
The public Python surface of LibreYOLO is the __all__ list in libreyolo/__init__.py. Package-level exports use from libreyolo import <name>; tracking and training protocols below use their named submodules.
Verified against LibreYOLO v1.6.0.

## Entry points

Factories load models or configure API clients. They are separated by call contract, not by
architecture.

| Factory | Loads | Prompt at call time | Extra required |
|---|---|---|---|
| `LibreYOLO` | Promptless families, by sniffing the checkpoint or file suffix | | |
| `LibreSAM` | Promptable segmenters, by size alias | Points, boxes, or concept text | `sam` |
| `LibreVLM` | Generative vision-language detectors, by alias | Class vocabulary or a free-form prompt | `vlm` |
| `LibreOpenVocab` | Text-conditioned detectors, by alias | Class vocabulary | `openvocab` |
| `LibreEnsemble` | Two or more detectors, fused into one surface | | |

**Entry points**

```python
from libreyolo import LibreYOLO, LibreEnsemble

# Weight-sniffing factory over the promptless families.
detector = LibreYOLO("LibreYOLO9t.pt")

# Two or more detectors behind one prediction surface.
ens = LibreEnsemble(["LibreYOLO9t.pt", "LibreYOLO9s.pt"])

# The other three factories need an extra installed:
#   pip install 'libreyolo[sam]'        -> from libreyolo import LibreSAM
#   pip install 'libreyolo[vlm]'        -> from libreyolo import LibreVLM
#   pip install 'libreyolo[openvocab]'  -> from libreyolo import LibreOpenVocab
print(type(detector).__name__, ens.fusion)
```

`LibreYOLO` accepts checkpoint files and exported artifacts. Sibling factories accept model aliases; `LibreVLM` and `LibreVLA` also reload their own saved checkpoint directories.

```python
LibreYOLO(
    model_path: str,
    size: str | None = None,
    reg_max: int = 16,
    nb_classes: int | None = None,
    device: str = "auto",
    task: str | None = None,
    compute_units: str = "all",
)
```

`model_path` accepts a `.pt` checkpoint, an ONNX `.onnx` file, an ExecuTorch
`.pte`, an MNN `.mnn`, a TensorRT `.engine`, an OpenVINO, Paddle or ncnn
directory, or a Triton HTTP or HTTPS model URL. `size` and `nb_classes` are
read from the checkpoint when omitted. `compute_units` is read only for
CoreML `.mlpackage` loads and is one of `all`, `cpu_only`, `cpu_and_gpu`,
`cpu_and_ne`. `task` takes any canonical task name from `libreyolo.tasks.TASKS`.

**Load anything through one factory**

```python
from libreyolo import LibreYOLO, SAMPLE_IMAGE

model = LibreYOLO("LibreYOLO9t.pt")

# A single image source returns one Results; a list or directory
# returns a list of them.
result = model(SAMPLE_IMAGE)

print(result.boxes.xyxy)
print(result.names)
```

**Import a family class directly**

```python
from libreyolo import LibreYOLO9, SAMPLE_IMAGE

model = LibreYOLO9("LibreYOLO9t.pt", size="t")
result = model(SAMPLE_IMAGE)

print(len(result))
```

`LibreGround` maps instructions to image points; `LibreVLA` predicts robot action chunks; `LibreLLM` calls a compatible remote language-model endpoint. See the [grounding API](/docs/v1.6.0/reference/ground-api), [policy API](/docs/v1.6.0/reference/vla-api) and [language-model client](/docs/v1.6.0/reference/llm-api).

`LibreYOLO("hf://owner/repo@revision/filename")` loads Hub checkpoints. `model.push_to_hub(repo_id, private=False)` publishes a checkpoint and card. The [Hub reference](/docs/v1.6.0/reference/hugging-face) defines resolution and authentication.

## Family classes

Every family the factory can return is also exported by name, so a class can be
constructed directly when the checkpoint is known in advance. The constructors
follow `BaseModel.__init__`:

```python
Family(model_path, size, nb_classes=80, device="auto", task=None, **kwargs)
```

Constructor defaults vary by family; check its signature before constructing it directly. YOLO9 and its variants insert `reg_max: int = 16` after `size`.

Detection and multi-task families: `LibreYOLO9`, `LibreYOLO9E2E`,
`LibreYOLO9P2`, `LibreYOLONAS`, `LibreYOLOX`, `LibreYOLO7`, `LibreYOLO4`,
`LibreYOLO3`, `LibreYOLO2`, `LibreYOLO1`, `LibreRTDETR`, `LibreRTDETRv2`,
`LibreRTDETRv4`, `LibreRFDETR`, `LibreDFINE`, `LibreDOMEDETR`, `LibreDEIM`,
`LibreDEIMv2`, `LibreDETR`, `LibreDeformableDETR`, `LibreDINODETR`,
`LibreLWDETR`, `LibreMaskRCNN`, `LibreFCOS`, `LibreFasterRCNN`,
`LibreRetinaNet`, `LibreSSD`, `LibreCenterNet`, `LibreEfficientDet`,
`LibreEC`, `LibreGTR`, `LibreTinyFormer`, `LibrePICODET`, `LibrePPYOLOE`,
`LibreRTMDet`, `LibreFOMO`.

Dense-prediction families: `LibreMiDaS`, `LibreDepthAnythingV2`,
`LibreDepthAnything3`, `LibreZipDepth`, `LibreMoGe2`, `LibreTEED`,
`LibreDexiNed`, `LibreNAFNet`, `LibreRealESRGAN`, `LibreSwinIR`,
`LibreBiRefNet`, `LibreFeyNobg`, `LibreFCN`, `LibreEoMT`, `LibreDeepLabv3`,
`LibrePIDNet`, `LibrePPLiteSeg`, `LibreUNet`, `LibreSegformer`,
`LibreLingBotVision`, `LibreMarigoldV2`, `LibreDDColor`, `LibreHVICIDNet`,
`LibreLaMa`, `LibreQuickSRNet`, `LibreBEN2`, `LibreViTMatte`.

Classification and embedding families: `LibreViT`, `LibreMobileNetV4`,
`LibreConvNeXt`, `LibreDeiT`, `LibreSwin`, `LibreEfficientNetV2`, `LibreVGG`,
`LibreResNet`, `LibreAlexNet`, `LibreCLIP`, `LibreSigLIP2`, `LibreDINOv2`,
`LibreConvNeXtV2`, `LibrePE`, `LibreVJEPA2`, `LibreLeVJEPA`.

Other tasks: `LibreHRNet` and `LibreDEKR` (pose), `LibreL2CS` (gaze),
`LibrePPOCR` (ocr), `LibreFaceEmbedder` (embed), and the 3D detectors
`LibreFCOS3D`, `LibreDetAny3D`, `LibreWildDet3D` and `Libre3DMOOD` (detect3d).

The sibling tiers export their family classes too: `LibreSAM1`, `LibreSAM2`,
`LibreSAM3`, `LibreEdgeTAM`, `LibreMobileSAM`, `LibrePicoSAM3`;
`LibreGroundingDINO`, `LibreOWLv2`, `LibreOMDetTurbo`; `LibreLFM2VL`,
`LibreQwen3VL`, `LibreSmolVLM2`, `LibreInternVL3`, `LibreFlorence2`,
`LibreKosmos2`, `LibreLocateAnything`, `LibreGemma4`, `LibreMoondream`,
`LibreMolmo2`, `LibreNorthMicroVision`, `LibreMODUS` (also spelled
`LibreModus`); `LibreShowUI`, `LibreGroundFlorence2` and `LibreGroundQwen3VL`
behind `LibreGround`; `LibreSmolVLA`, `LibreACT` and `LibreDiffusionPolicy`
behind `LibreVLA`.

## Prediction surface

Calling a model runs inference. `predict` is an alias for `__call__`, so the
two are interchangeable.

```python
model(
    source=None,
    *,
    conf=0.25,
    iou=0.45,
    imgsz=None,
    device=None,
    classes=None,
    max_det=300,
    augment=False,
    save=False,
    batch=1,
    stream=False,
    stream_buffer=False,
    vid_stride=1,
    show=False,
    output_path=None,
    color_format="auto",
    tiling=False,
    overlap_ratio=0.2,
    output_file_format=None,
    cuda_graph=False,
    **kwargs,
)
```

A single image source returns one `Results`. A list, a tuple or a directory
returns a list of them, and `stream=True` returns a generator. The other
methods on the model object are documented on the
[model API page](/docs/v1.6.0/reference/model-api).

## Results payloads

`Results` and its payload classes are exported at package level:
`Results`, `Boxes`, `Masks`, `Keypoints`, `Points`, `Probs`, `OBB`, `Gaze`,
`SemanticMask`, `PanopticSegmentation`, `DepthMap`, `EdgeMap`, `NormalMap`,
`RestoredImage`, `Matte`, `Meshes`, `OCRRegions`, `Embeddings`, `Identities`.
Each one is described in [Results types](/docs/v1.6.0/reference/results-types).

`Boxes3D`, `AlbedoMap` and `Actions` add 3D cuboids, intrinsic albedo and action chunks. See [result types](/docs/v1.6.0/reference/results-types).

## Backends

Exported artifacts load through `LibreYOLO()` by file suffix, so the backend
classes are rarely constructed by hand. They are exported for the cases where
a backend has to be selected explicitly: `OnnxBackend`, `OpenVINOBackend`,
`PaddleBackend`, `TensorRTBackend`, `TritonBackend`, `NcnnBackend`,
`CoreMLBackend`, plus `create_triton_config`. `BaseExporter` is the exporter
registry behind `model.export()`.

## Validators

`model.val()` dispatches to the right validator by task, so these are exported
for direct use and for subclassing: `DetectionValidator`,
`SegmentationValidator`, `PoseValidator`, `SemanticValidator`,
`PanopticValidator`, `DepthValidator`, `NormalValidator`, `EdgeValidator`, and
the shared `ValidationConfig`.

## Tracking

`model.track()` selects a tracker by name. The tracker classes and their
configuration dataclasses are also exported: `ByteTracker` with `TrackConfig`,
`BoTSortTracker` with `BoTSortConfig`, and `OCSortTracker` with
`OCSortConfig`.

`libreyolo.tracking.Tracker` defines `reset()` and `update(results, image=None)` for custom tracker instances.

## Data helpers

`DATASETS_DIR` is the resolved dataset root, `load_data_config` reads a
dataset YAML, and `check_dataset` validates one. The task-specific loaders
named in [Dataset formats](/docs/v1.6.0/reference/dataset-formats) live in
`libreyolo.data` rather than at package level.

## Galleries and distillation

`Gallery` and `FaceGallery` hold enrolled identity vectors for the `embed`
task and produce the `Identities` payload. `Distiller` and
`get_distill_config` drive teacher-student training.

`libreyolo.training.TrainFitnessCallback` defines `fitness(metrics)` for custom checkpoint selection. See [fitness callbacks](/docs/v1.6.0/train/fitness-callbacks).

## Assets

`SAMPLE_IMAGE` is an absolute path to an image bundled with the package, so
every snippet in these docs runs without downloading a picture first.

## Lazy imports and renamed classes

Most sibling-tier names, the backends, the validators and the data helpers
resolve through the module-level `__getattr__`, so importing `libreyolo` does
not import their dependencies. The import still fails with a clear message
when the required extra is missing.

Two class names were renamed and the old spelling still resolves, with a
`DeprecationWarning`: `LibreYOLORTDETR` is now `LibreRTDETR`, and
`LibreYOLORFDETR` is now `LibreRFDETR`.