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.

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`
`LibreGen`	Generative models, by alias or local model directory	A text prompt (text to image) or an image (image to 3D)	`gen`
`LibreEnsemble`	Two or more detectors, fused into one surface

Entry points

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, and LibreGen loads a local model directory in a supported family's upstream format.

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

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

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

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), LibreWeVisOneVL; LibreShowUI, LibreGroundFlorence2 and LibreGroundQwen3VL behind LibreGround; LibreSmolVLA, LibreACT and LibreDiffusionPolicy behind LibreVLA; LibreFlux2Klein, LibreSanaSprint and LibreSperidlabsIdol behind LibreGen.

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,    agnostic_nms=False,    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.

agnostic_nms=True runs class-agnostic NMS: among boxes that overlap above iou, only the highest-scoring one is kept, whatever their classes. It runs on the family's finished detections, after the classes filter, and covers the detect, segment, pose and OBB tasks, with rotated IoU for oriented boxes. On any other task it raises ValueError.

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.

GeneratedImage and Gaussians carry the output of LibreGen: a generated image in Results.generated and a generated 3D object in Results.gaussians.

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.