use-libreyolo

Use LibreYOLO

LibreYOLO is an MIT-licensed CV library. Its API follows the YOLO standard, which means two things you can rely on:

1. CLI and Python mirror each other — same verbs (predict, train, val, export), same argument names. Use whichever the user prefers.
2. The CLI is self-describing. Never guess a flag — ask the binary (see Exact options below). This is also why this skill stays short: it teaches the shape, the tool supplies the details for the installed version.

Flagship models: YOLO9 (CNN) and RF-DETR (transformer). Weights auto-download on first use — pass a name like LibreYOLO9t.pt / LibreRFDETRn.pt, or a path to the user's own .pt.

Setup

pip install libreyolo
libreyolo checks      # verify install, CUDA/MPS, and optional export backends

The base install is lightweight. Some features need optional extras — install them as libreyolo[extra] (or libreyolo[all]). Available extras: onnx, rfdetr, eomt, tensorrt, openvino, ncnn, tflite, coreml, tracking, gaze, rtdetr, vlm, sam, openvocab, clip, label, plots, lora, tensorboard, mlflow, wandb, all. libreyolo checks reports which are present.

The four verbs

Arguments take either YOLO-style key=value or --key value. Examples use key=value. Tip: save=true writes annotated outputs under runs/ — the fastest way to eyeball results while experimenting.

Predict — run inference

libreyolo predict model=LibreYOLO9t.pt source=path/to/img_or_dir conf=0.25 save=true

from libreyolo import LibreYOLO, SAMPLE_IMAGE
model = LibreYOLO("LibreYOLO9t.pt")
results = model(SAMPLE_IMAGE, save=True)   # equivalently: model.predict(source=...)

Train — needs a YOLO-format dataset YAML

libreyolo train model=LibreYOLO9t.pt data=coco8.yaml epochs=100 imgsz=640 batch=16 device=0

model.train(data="coco8.yaml", epochs=100, imgsz=640)

Caveat to the "same arguments" rule: RF-DETR's train signature differs — e.g. batch_size (not batch), lr (not lr0), output_dir (not project). Confirm with libreyolo train --help-json for the loaded model.

Validate — mAP on a split

libreyolo val model=runs/train/exp/weights/best.pt data=coco8.yaml save_json=true save_plots=true

Export — onnx · torchscript · tensorrt · openvino · ncnn · tflite · coreml

libreyolo export model=runs/train/exp/weights/best.pt format=onnx half=true

Run libreyolo formats for each format's extension and FP16/INT8 support.

Reading results

predict/track return a single Results for a single image, or a list of Results for multiple inputs (a directory, a list, or video frames). Index the list, not a single Results — indexing a Results selects one detection. Read them programmatically rather than re-parsing saved files:

r = model("img.jpg")          # one Results (single image); use model([...])  / a dir for a list
len(r)              # number of detections
r.boxes.xyxy        # (N, 4) boxes; also .xywh, .conf, .cls, .id (tracking)
r.masks             # segmentation masks (segment task)
r.keypoints         # pose keypoints
r.probs / r.obb / r.gaze   # classify / oriented-box / gaze tasks
r.names             # class-id → label map

For scripting from the CLI, add --json to get machine-readable results on stdout.

Monitoring a training run

Every train run writes live monitoring files into its save_dir. To check on a run, read status.json (a few tokens) instead of tailing logs:

cat runs/train/exp/status.json   # state (running/completed/failed), epoch,
                                 # progress, eta_seconds, latest/best metrics,
                                 # and on failure the error message

The run's console output is tee'd to train.log, and metrics.jsonl holds the full per-epoch history. For a human, libreyolo monitor [run_or_root] serves a read-only browser dashboard (live charts, log, val images) over those files — it works on live, finished, or crashed runs, and one server handles every run under the root (?run= in the URL selects one).

Beyond the four verbs

• Inference on an exported model — the same constructor loads an exported file and runs through the matching backend, so export isn't a dead end:

  model = LibreYOLO("best.onnx")     # also .torchscript, .engine, OpenVINO, CoreML
  model("img.jpg", save=True)        # same predict API as a .pt
  

• Object tracking — model.track(...) assigns IDs across video frames. Two motion trackers: ByteTrack (tracker="bytetrack", default) and OC-SORT. IDs come back on r.boxes.id. Needs libreyolo[tracking].
• Tiled inference for large images — predict(..., tiling=True, overlap_ratio=0.2) slices high-resolution images so small objects aren't lost, then merges detections.
• Video & streaming — point source at a video file, or pass stream=True to get a per-frame generator (r.frame_idx per result); vid_stride=N samples every Nth frame.
• Ensembling — LibreEnsemble combines multiple detectors; ExternalDetector folds in a non-LibreYOLO model.

Supported tasks

detect (suffixless default), segment, semantic, pose, classify, gaze, obb, point, depth, restore. Detection — plus RF-DETR segmentation — is the heavily-tested core; other task/family combinations vary in maturity, so check the README compatibility table before relying on one. Task outputs land on matching Results fields (r.semantic_mask, r.depth_map, r.restored, r.points, …).

Models

libreyolo models lists every family with its sizes and exact names — treat it as the source of truth. By tier:

• Flagship: YOLO9 (CNN), RF-DETR (transformer) — detection + segmentation (RF-DETR also pose + OBB).
• Other detectors: YOLOX, YOLO9-E2E, YOLO9-P2 (stride-4 small-object), YOLO-NAS, D-FINE, DEIM, DEIMv2, RT-DETR / v2 / v4, PicoDet, RTMDet, EC, and the inference-only classic lineage YOLO2/3/4/7.
• Specialized: L2CS (gaze), DepthAnythingV2 (depth), FOMO (point), NAFNet (restore: deblur/denoise), EoMT + PIDNet + DINOv2 (semantic).
• Classifiers (ImageNet-1k, native timm ports — predict logits are bit-identical to timm): MobileNetV4 (s/m/l), ConvNeXt (t/s/b), EfficientNetV2 (b0–b3), ResNet (18/34/50/101). Names carry the -cls suffix, e.g. model = LibreYOLO("LibreResNet50-cls.pt"). Fine-tune on an ImageFolder root (or a known name/.zip URL) with model.train(data=...).
• Zero-shot / promptable tiers (need [openvocab] / [sam] / [clip] / [vlm]): LibreOpenVocab (text-vocabulary detection), LibreSAM / LibreSAM2 / LibreMobileSAM (point/box-prompted masks), LibreCLIP (zero-shot classify), and the LibreVLM family (vision-language detection). For the exact model aliases in each tier, use libreyolo models and the dedicated guide skills/use-libreyolo-zero-shot/.

The UI

libreyolo ui          # drag/drop/paste images in the browser, pick a model, see results

A local web app with almost no extra dependencies — the easiest way to try most models without writing any code. Great for quick experimentation.

Other commands worth knowing

• libreyolo label [data=<dataset-or-folder>] — browser labelling tool (boxes/masks/classes) that writes YOLO-format labels; libreyolo[label] adds SAM click-to-mask assist.
• libreyolo doctor <dataset.yaml> — dataset sanity checks (corrupt images, label mismatches, leakage, tiny objects) before you burn GPU hours on a bad dataset.
• libreyolo profile run|infer ... — throughput/latency profiling; see skills/libreyolo-profiling/.

Exact, version-correct options

The CLI is the source of truth for the installed version. Prefer these over recalling flags from memory:

libreyolo --help                 # list every command
libreyolo train --help-json      # full argument schema for one command, as JSON
libreyolo models                 # list model families, sizes, and names
libreyolo formats                # list export formats and their capabilities
libreyolo info model=...         # resolved family / size / task / device / classes
libreyolo metadata path=...      # raw metadata embedded in a checkpoint
libreyolo predict ... --json     # machine-readable results to stdout
libreyolo ... --quiet            # suppress progress output (good for scripting)

In Python the same kwargs apply; help(LibreYOLO.train) and model.info() describe the loaded model.

Notes

• Datasets are standard YOLO format, so existing YOLO dataset YAMLs (e.g. coco8.yaml) work unchanged.
• Outputs land under runs/ (runs/detect, runs/train, runs/val).
• Stuck or an import/CUDA error? Run libreyolo checks first — it diagnoses the environment and export-backend problems before you debug anything else.
• Deeper guides (concepts, dataset format, per-task details) live at https://www.libreyolo.com/docs — but for exact flags and what the installed version supports, the binary above is authoritative.