1
pip install libreyolo

1
git clone https://github.com/LibreYOLO/libreyolo.git
2
cd libreyolo
3
pip install -e .

1
# ONNX export and inference
2
pip install libreyolo[onnx]
3
# or: pip install onnx onnxsim onnxruntime
4
5
# RT-DETR compatibility extra (currently no extra packages)
6
pip install libreyolo[rtdetr]
7
8
# RF-DETR support
9
pip install libreyolo[rfdetr]
10
# or: pip install transformers
11
12
# TensorRT export and inference (NVIDIA GPU)
13
pip install libreyolo[tensorrt]
14
# Installs TensorRT CUDA 12 Python packages on Linux/Windows.
15
# Host driver/CUDA compatibility still matters.
16
17
# OpenVINO export and inference (Intel CPU/GPU/VPU)
18
pip install libreyolo[openvino]
19
# INT8 export also needs: pip install nncf
20
21
# NCNN export and inference
22
pip install libreyolo[ncnn]
23
# or: pip install pnnx ncnn
24
25
# TFLite export + LiteRT runtime backend (Python 3.12+)
26
pip install libreyolo[tflite]
27
# "litert" is an alias extra: pip install libreyolo[litert]
28
29
# Tracking API compatibility extra
30
pip install libreyolo[tracking]
31
# Tracking dependencies are part of the base install; Deep OC-SORT's ReID
32
# embedder weights auto-download on first use.
33
34
# CoreML export and inference (macOS only for runtime)
35
pip install libreyolo[coreml]
36
# or: pip install coremltools
37
38
# L2CS gaze optional auto-download helper
39
pip install libreyolo[gaze]
40
41
# Promptable segmentation (LibreSAM: SAM-1, SAM-2, SAM 3, MobileSAM,
42
# EdgeTAM, PicoSAM3)
43
pip install libreyolo[sam]
44
45
# Open-vocabulary detection (Grounding DINO, OWLv2, OmDet-Turbo, OV-DEIM)
46
pip install libreyolo[openvocab]
47
48
# LibreLabel AI assist (SAM click-to-mask)
49
pip install libreyolo[label]
50
51
# Zero-shot classification
52
pip install libreyolo[clip]       # CLIP
53
pip install libreyolo[siglip2]    # SigLIP2 tokenizer (SentencePiece)
54
55
# LoRA fine-tuning (peft)
56
pip install libreyolo[lora]
57
58
# Experiment loggers
59
pip install libreyolo[tensorboard]   # or [mlflow], [wandb]
60
61
# EoMT instance / panoptic segmentation
62
pip install libreyolo[eomt]
63
64
# Install every optional LibreYOLO extra
65
pip install libreyolo[all]

1
# ONNX environment
2
uv venv .venv-onnx
3
uv pip install --python .venv-onnx/bin/python -e '.[onnx]'
4
5
# RT-DETR environment
6
uv venv .venv-rtdetr
7
uv pip install --python .venv-rtdetr/bin/python -e '.[rtdetr]'
8
9
# Repeat with .[rfdetr], .[openvino], .[ncnn], .[coreml], .[gaze], .[tracking], or .[tensorrt] as needed

1
from libreyolo import LibreYOLO, SAMPLE_IMAGE
2
3
# Use the official checkpoint name and let the factory resolve the details
4
model = LibreYOLO("LibreYOLO9c.pt")
5
6
# Run on a single image (SAMPLE_IMAGE ships with the package)
7
result = model(SAMPLE_IMAGE)
8
9
print(f"Found {len(result)} objects")
10
print(result.boxes.xyxy)   # bounding boxes (N, 4)
11
print(result.boxes.conf)   # confidence scores (N,)
12
print(result.boxes.cls)    # class IDs (N,)

1
from libreyolo import LibreYOLO, SAMPLE_IMAGE
2
3
# Same factory, same call shape - just point at an RF-DETR checkpoint
4
model = LibreYOLO("LibreRFDETRs.pt")
5
result = model(SAMPLE_IMAGE)
6
7
print(f"Found {len(result)} objects")
8
print(result.boxes.xyxy)

1
result = model(SAMPLE_IMAGE, save=True)
2
print(result.saved_path)   # e.g. runs/detect/predict/parkour.jpg

1
results = model("images/", save=True, batch=4)
2
for r in results:
3
    print(f"{r.path}: {len(r)} detections")

1
from libreyolo import LibreYOLO
2
3
model = LibreYOLO("LibreYOLO9c.pt")   # detection

1
from libreyolo import LibreYOLO
2
3
model = LibreYOLO("LibreRFDETRs.pt")           # detect (validated)
4
# model = LibreYOLO("LibreRFDETRs-seg.pt")     # segment (validated)
5
# model = LibreYOLO("LibreRFDETRx-pose.pt")    # pose  (research preview)
6
# model = LibreYOLO("LibreRFDETRn-obb.pt")     # obb   (research preview)

1
from libreyolo import LibreYOLO
2
3
# Default: YOLO9 detection
4
model = LibreYOLO("LibreYOLO9c.pt")
5
6
# Flagship transformer: RF-DETR
7
model = LibreYOLO("LibreRFDETRs.pt")
8
model = LibreYOLO("LibreRFDETRs-seg.pt")        # validated segmentation
9
10
# The task suffix selects the task
11
model = LibreYOLO("LibreMobileNetV4s-cls.pt")   # classification (Apache, ImageNet-1k)
12
model = LibreYOLO("LibreDINOv2n.pt")            # semantic segmentation
13
model = LibreYOLO("LibreDepthAnythingV2s-depth.pt")  # monocular depth
14
model = LibreYOLO("LibreFOMOs-point.pt")        # point localization (local weights)
15
16
# New in v1.4.0
17
model = LibreYOLO("LibreSegformerb2-sem.pt")    # semantic segmentation
18
model = LibreYOLO("LibreEoMTb-panoptic.pt")     # panoptic segmentation
19
model = LibreYOLO("LibreSwinIRm-restore.pt")    # 4x super-resolution
20
model = LibreYOLO("LibreBiRefNetl-matte.pt")    # background removal
21
model = LibreYOLO("LibrePPOCRt-ocr.pt")         # OCR (text detection + recognition)
22
model = LibreYOLO("LibreZipDepthb-depth.pt")    # depth
23
24
# Exported deployment formats
25
model = LibreYOLO("model.onnx")                 # ONNX Runtime
26
model = LibreYOLO("model.engine")               # TensorRT
27
model = LibreYOLO("model.mlpackage")            # CoreML (macOS)
28
model = LibreYOLO("model_openvino/")            # OpenVINO (directory)
29
model = LibreYOLO("model_ncnn/")                # NCNN (directory)
30
model = LibreYOLO("model.tflite")               # TFLite / LiteRT (new in v1.4.0)

1
Libre<FAMILY><size>[-<task>].pt

1
explicit task=  →  checkpoint["task"]  →  filename suffix  →  family default

1
from libreyolo import LibreYOLO
2
3
# 1. Filename suffix decides → segment
4
model = LibreYOLO("LibreRFDETRs-seg.pt")
5
6
# 2. Override regardless of filename
7
model = LibreYOLO("custom_weights.pt", task="segment")
8
9
# 3. Detection is implicit
10
model = LibreYOLO("LibreYOLO9c.pt")  # task="detect"

1
# Detection (implicit)
2
LibreYOLO9c.pt
3
LibreRFDETRs.pt
4
LibreRTDETRr50.pt
5
6
# Instance segmentation (-seg)
7
LibreRFDETRs-seg.pt
8
LibreECm-seg.pt
9
10
# Semantic segmentation (-sem)
11
LibreDINOv2n.pt          # semantic is DINOv2's default; -sem optional
12
LibreSegformerb0-sem.pt  # SegFormer requires the -sem suffix
13
14
# Panoptic segmentation (-panoptic)
15
LibreEoMTs-panoptic.pt
16
17
# Pose (-pose)
18
LibreYOLONASn-pose.pt
19
LibreECs-pose.pt
20
LibreRFDETRx-pose.pt     # preview
21
22
# Oriented boxes (-obb)
23
LibreRFDETRn-obb.pt      # preview
24
25
# Classification (-cls)
26
LibreMobileNetV4s-cls.pt
27
LibreConvNeXtt-cls.pt
28
LibreEfficientNetV2b0-cls.pt
29
LibreDINOv2n-cls.pt      # DINOv2 linear probe
30
LibreSigLIP2b16-cls.pt   # zero-shot
31
32
# Depth (-depth)
33
LibreDepthAnythingV2s-depth.pt
34
LibreZipDepthb-depth.pt
35
36
# Restoration / super-resolution (-restore)
37
LibreNAFNetl-restore-sidd.pt
38
LibreSwinIRm-restore.pt
39
LibreRealESRGANx4-restore.pt
40
41
# Background removal (-matte)
42
LibreBiRefNetl-matte.pt
43
44
# OCR (-ocr)
45
LibrePPOCRt-ocr.pt
46
47
# Point (-point)
48
LibreFOMOs-point.pt
49
50
# Gaze (-gaze optional; only task for L2CS)
51
LibreL2CSr50.pt

1
result = model("image.jpg")

1
result = model(
2
    "image.jpg",
3
    conf=0.25,            # confidence threshold (default: 0.25)
4
    iou=0.45,             # NMS IoU threshold (default: 0.45)
5
    imgsz=640,            # input size override (default: model's native)
6
    device="auto",        # "auto", "cpu", "mps", "0", "cuda:0", ...
7
    classes=[0, 2, 5],    # filter to specific class IDs (default: all)
8
    max_det=300,          # max detections per image (default: 300)
9
    augment=False,        # test-time augmentation where implemented
10
    save=True,            # save annotated image (default: False)
11
    batch=4,              # directory batch size
12
    stream=False,         # video only: yield frame results instead of a list
13
    vid_stride=1,         # video only: process every N-th frame
14
    show=False,           # video only: display annotated frames
15
    tiling=False,         # large-image tiled detection
16
    overlap_ratio=0.2,    # tile overlap ratio
17
    output_path="out/",   # where to save (default: runs/detect/predict*/)
18
    color_format="auto",  # "auto", "rgb", or "bgr"
19
    output_file_format="png",  # output format: "jpg", "png", "webp"
20
)

1
# File path (string or pathlib.Path)
2
result = model("photo.jpg")
3
result = model(Path("photo.jpg"))
4
5
# URL
6
result = model("https://example.com/image.jpg")
7
result = model("s3://bucket/image.jpg")
8
result = model("gs://bucket/image.jpg")
9
10
# PIL Image
11
from PIL import Image
12
img = Image.open("photo.jpg")
13
result = model(img)
14
15
# NumPy array (HWC or CHW, RGB or BGR, uint8 or float32)
16
import numpy as np
17
arr = np.random.randint(0, 255, (480, 640, 3), dtype=np.uint8)
18
result = model(arr)
19
20
# OpenCV (BGR) - specify color_format
21
import cv2
22
frame = cv2.imread("photo.jpg")
23
result = model(frame, color_format="bgr")
24
25
# PyTorch tensor (CHW or NCHW)
26
import torch
27
tensor = torch.randn(3, 640, 640)
28
result = model(tensor)
29
30
# Raw bytes
31
with open("photo.jpg", "rb") as f:
32
    result = model(f.read())
33
34
# BytesIO
35
from io import BytesIO
36
result = model(BytesIO(open("photo.jpg", "rb").read()))
37
38
# Directory of images
39
results = model("images/", batch=4)

1
result = model("image.jpg")
2
3
# Number of detections
4
len(result)  # e.g., 5
5
6
# Bounding boxes in xyxy format (x1, y1, x2, y2)
7
result.boxes.xyxy        # tensor of shape (N, 4)
8
9
# Bounding boxes in xywh format (center_x, center_y, width, height)
10
result.boxes.xywh        # tensor of shape (N, 4)
11
12
# Confidence scores
13
result.boxes.conf        # tensor of shape (N,)
14
15
# Class IDs
16
result.boxes.cls         # tensor of shape (N,)
17
18
# Combined data: [x1, y1, x2, y2, conf, cls]
19
# Tracking adds a track_id column before conf/cls.
20
result.boxes.data        # shape (N, 6), or (N, 7) when tracked
21
22
# Metadata
23
result.orig_shape        # (height, width) of original image
24
result.path              # source file path (or None)
25
result.names             # {0: "person", 1: "bicycle", ...}
26
27
# Move to CPU / convert to numpy
28
result_cpu = result.cpu()
29
boxes_np = result.boxes.numpy()

1
# Only detect people (class 0) and cars (class 2)
2
result = model("image.jpg", classes=[0, 2])

1
import numpy as np
2
from libreyolo import LibreYOLO
3
4
model = LibreYOLO("LibreYOLO9c.pt")
5
6
frames = [
7
    np.random.randint(0, 255, (480, 640, 3), dtype=np.uint8),
8
    np.random.randint(0, 255, (480, 640, 3), dtype=np.uint8),
9
    np.random.randint(0, 255, (480, 640, 3), dtype=np.uint8),
10
]
11
12
results = model(frames, batch=4)   # list/tuple -> true batched inference
13
for r in results:
14
    print(len(r), r.boxes.xyxy.shape)

1
meta = model.info(detailed=False, verbose=True)
2
# meta -> {"family": ..., "size": ..., "task": ..., "params": ..., "imgsz": ..., "names": {...}, ...}

1
result = model(
2
    "large_aerial_image.jpg",
3
    tiling=True,
4
    overlap_ratio=0.2,   # 20% overlap between tiles (default)
5
    save=True,
6
)
7
8
# Extra metadata on tiled results
9
result.tiled           # True
10
result.num_tiles       # number of tiles used
11
result.saved_path      # output directory when save=True
12
result.tiles_path      # directory containing per-tile crops
13
result.grid_path       # grid visualization image

1
from libreyolo import LibreYOLO
2
3
model = LibreYOLO("LibreYOLO9c.pt")
4
results = model("clip.mp4", save=True)
5
# Saved under runs/detect/predict*/clip.mp4

1
for result in model("long_clip.mp4", stream=True):
2
    print(f"frame {result.frame_idx}: {len(result)} detections")

1
# Process every 2nd frame (halves compute and saved fps)
2
results = model("clip.mp4", vid_stride=2, save=True)

1
# Display annotated frames in an OpenCV window while processing
2
results = model("clip.mp4", show=True)

1
from libreyolo import LibreYOLO
2
from libreyolo.utils.video import VideoSource, VideoWriter
3
4
model = LibreYOLO("LibreYOLO9c.pt")
5
6
with VideoSource("clip.mp4", vid_stride=1) as src, \
7
     VideoWriter("out.mp4", fps=src.fps, width=src.width, height=src.height) as out:
8
    for frame_bgr, frame_idx in src:
9
        result = model(frame_bgr, color_format="bgr")
10
        # ... draw, transform, etc.
11
        out.write_frame(frame_bgr)

1
pip install libreyolo[tracking]   # compatibility extra; tracking deps ship in base dev install

1
from libreyolo import LibreYOLO
2
3
model = LibreYOLO("LibreYOLO9c.pt")
4
5
for result in model.track(
6
    "clip.mp4",
7
    track_conf=0.25,
8
    iou=0.45,
9
    save=True,             # writes runs/track/<video_stem>.mp4 by default
10
    vid_stride=1,
11
):
12
    print(result.frame_idx, result.track_id)

1
from libreyolo import LibreYOLO, ByteTracker
2
from libreyolo.utils.video import VideoSource
3
4
model = LibreYOLO("LibreYOLO9c.pt")
5
tracker = ByteTracker()
6
7
with VideoSource("clip.mp4") as src:
8
    for frame_bgr, frame_idx in src:
9
        result = model(frame_bgr, color_format="bgr", conf=0.1)
10
        tracked = tracker.update(result)
11
12
        for i in range(len(tracked.boxes)):
13
            track_id = int(tracked.boxes.id[i])
14
            xyxy = tracked.boxes.xyxy[i].tolist()
15
            cls = int(tracked.boxes.cls[i])
16
            print(f"frame {frame_idx} - id {track_id} cls {cls} {xyxy}")

1
from libreyolo import ByteTracker, TrackConfig
2
3
cfg = TrackConfig(
4
    track_high_thresh=0.25,           # first-stage match threshold
5
    track_low_thresh=0.1,             # second-stage (low-conf recovery)
6
    new_track_thresh=0.25,            # minimum conf to start a new track
7
    match_thresh=0.8,                 # IoU cost cutoff (stage 1)
8
    match_thresh_low=0.5,             # IoU cost cutoff (stage 2)
9
    match_thresh_unconfirmed=0.7,     # IoU cost cutoff for unconfirmed tracks
10
    track_buffer=30,                  # frames to keep lost tracks before removal
11
    frame_rate=30,                    # scales track_buffer
12
    fuse_score=True,                  # multiply IoU by detection score
13
    minimum_consecutive_frames=1,     # frames to confirm a new track
14
)
15
tracker = ByteTracker(config=cfg)

1
tracker.reset()   # clears tracked / lost / removed lists and the ID counter

1
from libreyolo import LibreYOLO
2
3
model = LibreYOLO("LibreYOLO9c.pt")
4
5
for result in model.track(
6
    "clip.mp4",
7
    tracker="ocsort",      # "bytetrack" (default) or "ocsort"
8
    track_conf=0.25,       # maps to OC-SORT det_thresh
9
    iou=0.45,
10
    save=True,
11
):
12
    print(result.frame_idx, result.track_id)

1
from libreyolo import LibreYOLO, OCSortConfig
2
3
cfg = OCSortConfig(
4
    det_thresh=0.25,     # boxes above this drive association and spawn new tracks
5
    max_age=30,          # frames a track survives without an observation
6
    min_hits=3,          # consecutive hits before a track is reported
7
    iou_threshold=0.3,   # minimum IoU for a valid association
8
    delta_t=3,           # frame span used to estimate velocity direction
9
    inertia=0.2,         # weight of the velocity-direction (momentum) term
10
    use_byte=False,      # enable the BYTE low-score recovery pass
11
)
12
13
model = LibreYOLO("LibreYOLO9c.pt")
14
for result in model.track("clip.mp4", tracker_config=cfg, save=True):
15
    print(result.frame_idx, result.track_id)

1
from libreyolo import LibreYOLO, BoTSortConfig
2
3
model = LibreYOLO("LibreYOLO9c.pt")
4
5
# Select by name with defaults
6
for result in model.track("drone.mp4", tracker="botsort", save=True):
7
    print(result.frame_idx, result.track_id)
8
9
# Or configure it: a config instance selects the tracker by type
10
cfg = BoTSortConfig(
11
    track_high_thresh=0.25,
12
    track_buffer=30,
13
    enable_cmc=True,              # camera-motion compensation on (default)
14
    cmc_method="sparseOptFlow",   # the shipped CMC estimator
15
    cmc_downscale=2,              # estimate flow at half resolution
16
)
17
for result in model.track("drone.mp4", tracker_config=cfg, save=True):
18
    print(result.frame_idx, result.track_id)

1
from libreyolo import LibreYOLO
2
from libreyolo.tracking import DeepOCSortConfig
3
4
model = LibreYOLO("LibreYOLO9c.pt")
5
6
# Defaults: OSNet-AIN embedder, auto-downloaded
7
for result in model.track("mall.mp4", tracker="deepocsort", save=True):
8
    print(result.frame_idx, result.track_id)
9
10
# Tune the appearance term, or plug in your own embedder
11
cfg = DeepOCSortConfig(
12
    det_thresh=0.25,
13
    embedder="osnet_ain_x0_25",   # or a callable: (frame, boxes_xyxy) -> (N, D) features
14
    w_association_emb=0.75,       # weight of appearance vs motion in matching
15
    alpha_fixed_emb=0.95,         # EMA smoothing of per-track embeddings
16
)
17
for result in model.track("mall.mp4", tracker_config=cfg, save=True):
18
    print(result.frame_idx, result.track_id)

1
from libreyolo import LibreEnsemble
2
3
# 加权框融合（WBF，默认），只保留两个模型都找到的框
4
ens = LibreEnsemble(["LibreYOLO9s.pt", "LibreRFDETRs.pt"], min_votes=2)
5
6
result = ens("image.jpg", conf=0.25)
7
print(result.boxes.xyxy)
8
print(result.names)     # 统一后的（并集）类别表

1
ens = LibreEnsemble(
2
    ["LibreYOLO9s.pt", "LibreRFDETRs.pt"],
3
    weights=[1.0, 1.4],     # 让融合结果更偏向第二个成员
4
    fusion="wbf",           # "wbf" | "wbf_seeded" | "nms" | 自定义可调用对象
5
    fusion_iou=0.55,        # 用于聚类的 IoU，不是成员的 NMS
6
    min_votes=1,
7
)
8
9
result = ens("image.jpg", conf=[0.25, 0.4])   # 每个成员单独的置信度阈值