This is the documentation for LibreYOLO 1.6.0. See the current version.

Entry points

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

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 LibreOpenVocabprint(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.

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.

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)

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, policy API and language-model client.

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 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__:

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.

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.

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.

Boxes3D, AlbedoMap and Actions add 3D cuboids, intrinsic albedo and action chunks. See result 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 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.

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.