LibreYOLO

https://www.libreyolo.com/docs
Admin
LibreYOLO is an MIT-licensed object detection library providing a unified Python API across YOLOX,...
Tokens:448,621
Snippets:3,978
Trust Score:2.1
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install libreyolo[executorch]

Source: https://www.libreyolo.com/docs/export/executorch.md

Install the ExecuTorch extra. This extra is deliberately outside libreyolo[all] because ExecuTorch pins the Torch version it works with, so install it into an environment you are willing to constrain.

```bash
pip install "libreyolo[executorch]"
```

--------------------------------

### Install LibreYOLO with extras (e.g., rfdetr, onnx)

Source: https://www.libreyolo.com/docs/install.md

Installs libreyolo with specified extras. Extras are comma-separated to combine several in one install.

```bash
# Comma-separate to combine several in one install.
pip install "libreyolo[rfdetr,onnx]"
```

--------------------------------

### Install openvocab extra

Source: https://www.libreyolo.com/docs/reference/openvocab-api.md

Install the open-vocabulary tier with the openvocab extra. Required before using LibreOpenVocab.

```bash
pip install 'libreyolo[openvocab]'
```

--------------------------------

### Install EdgeTAM with sam extra

Source: https://www.libreyolo.com/docs/models/edgetam.md

Install libreyolo with the 'sam' extra to get EdgeTAM support, which pulls in transformers and timm.

```bash
pip install "libreyolo[sam]"
```

--------------------------------

### Install CLIP extra with pip

Source: https://www.libreyolo.com/docs/models/clip.md

Install the 'clip' extra to get the packages needed for the vendored BPE tokenizer.

```bash
pip install "libreyolo[clip]"
```

--------------------------------

### Install LibreYOLO on the box

Source: https://www.libreyolo.com/docs/train/cloud-gpus.md

Install libreyolo and the extras needed for the run (rfdetr, lora, onnx). Install PyTorch first if the image lacks a matching CUDA build to avoid CPU-only torch.

```bash
pip install libreyolo

# Add only the extras the run needs. rfdetr for RF-DETR training,
# lora for parameter-efficient fine-tuning, onnx to export afterwards.
pip install "libreyolo[rfdetr,lora]"
```

--------------------------------

### Install with lora extra

Source: https://www.libreyolo.com/docs/models/convnext.md

Install LibreYOLO with the 'lora' extra, required for adapter fine-tuning with lora=True.

```bash
pip install "libreyolo[lora]"
```

--------------------------------

### Installation

Source: https://www.libreyolo.com/docs/models/sensenova-vision.md

Install LibreYOLO with the sensenova extra to use SenseNova-Vision. This pulls in accelerate and, on non-macOS platforms, bitsandbytes for 4-bit loading.

```APIDOC
## Install

### Description
Install LibreYOLO with the sensenova extra to use SenseNova-Vision. This pulls in accelerate and, on non-macOS platforms, bitsandbytes for 4-bit loading.

### Command
```bash
pip install "libreyolo[sensenova]"
```

### Notes
- The checkpoint is mirrored on Hugging Face under LibreYOLO's own org and downloads automatically on first use.
- The checkpoint is CC BY-NC 4.0, non-commercial use only; the loader prints that notice before every automatic download.
```

--------------------------------

### Install LibreYOLO with openvocab extra

Source: https://www.libreyolo.com/docs/models/grounding-dino.md

Install command for the open-vocabulary detector tier, which pulls in transformers and timm.

```bash
pip install "libreyolo[openvocab]"
```

--------------------------------

### Install LibreYOLO from source

Source: https://www.libreyolo.com/docs/install.md

Clones the stable 'release' branch and installs in editable mode. The integration branch is 'dev'.

```bash
git clone https://github.com/LibreYOLO/libreyolo.git
cd libreyolo
pip install -e .
```

--------------------------------

### Install the sam extra

Source: https://www.libreyolo.com/docs/reference/sam-api.md

Install the 'sam' extra required by the LibreSAM tier.

```bash
pip install 'libreyolo[sam]'
```

--------------------------------

### Install LibreYOLO

Source: https://www.libreyolo.com/docs/export/torchscript.md

Install the base package. TorchScript export requires no extra dependencies because torch.jit ships with PyTorch.

```bash
pip install libreyolo
```

--------------------------------

### Install LibreMODUS extra

Source: https://www.libreyolo.com/docs/models/libremodus.md

Install the libreyolo[modus] extra, which pulls in accelerate for big-model dispatch.

```bash
pip install "libreyolo[modus]"
```

--------------------------------

### Install Hailo packages and run device check

Source: https://www.libreyolo.com/docs/export/hailo.md

Install the required Hailo packages on Raspberry Pi 5 with AI Kit or AI HAT+. The first command installs dkms and hailo-all, and the second verifies the device and identifies the architecture.

```bash
sudo apt install dkms hailo-all
```

--------------------------------

### Install hub-kernels extra

Source: https://www.libreyolo.com/docs/reference/kernels.md

Installs the optional `libreyolo[hub-kernels]` package to enable Hub-backed kernels. Without this extra, no network request is made and behavior is unchanged.

```bash
pip install "libreyolo[hub-kernels]"
```

--------------------------------

### Basic libreyolo label example

Source: https://www.libreyolo.com/docs/cli/label.md

Opens the project home; pick or create a dataset in the browser.

```bash
# Opens the project home; pick or create a dataset in the browser.
libreyolo label
```

--------------------------------

### CLI: Run QAT from the command line

Source: https://www.libreyolo.com/docs/export/quantization.md

Runs QAT via the libreyolo CLI. Use the --model flag with a quantized model and specify finetune learning rates with --lr0.

```bash
libreyolo train --model LibreYOLO9s-int8.pt --data coco8.yaml --epochs 5 --lr0 1e-4
```

--------------------------------

### List available models and formats

Source: https://www.libreyolo.com/docs/cli/utilities.md

Shows how to list available models and query supported formats for a given family and task.

```bash
libreyolo models
libreyolo formats family=yolo9 task=detect
```

--------------------------------

### Python: print libreyolo.__version__

Source: https://www.libreyolo.com/docs/install.md

Use in a Python session to confirm the library is importable and print the installed version. No special setup is required.

```python
import libreyolo

print(libreyolo.__version__)
```

--------------------------------

### Train RF-DETR with Python (LibreYOLO)

Source: https://www.libreyolo.com/docs/models/rf-detr.md

Starts training from a published checkpoint. Note that passing pretrained=False is ignored by the native trainer, so you cannot get a randomly initialized model this way.

```python
from libreyolo import LibreYOLO

model = LibreYOLO("LibreRFDETRs.pt")
model.train(data="my-dataset.yaml", epochs=50, imgsz=512, batch=8, lr0=1e-4)
```

--------------------------------

### Basic quantization with int8 recipe

Source: https://www.libreyolo.com/docs/cli/quantize.md

Basic quantization example. Calibrates on coco128 and writes LibreYOLO9s-int8.pt.

```bash
# Calibrates on coco128 and writes LibreYOLO9s-int8.pt
libreyolo quantize model=LibreYOLO9s.pt recipe=int8
```

--------------------------------

### Read metadata off a checkpoint with unwrap_libreyolo_checkpoint

Source: https://www.libreyolo.com/docs/reference/checkpoint-schema.md

Loads a checkpoint saved by LibreYOLO, unwraps it to get the state dict and metadata, then prints selected metadata fields and the tensor count. Requires a local checkpoint path; the example first downloads and re-saves 'LibreYOLO9t.pt' as 'roundtrip.pt'.

```python
from libreyolo import LibreYOLO
from libreyolo.utils.serialization import unwrap_libreyolo_checkpoint
import torch

# Download a checkpoint, then re-save it so a local path exists.
LibreYOLO("LibreYOLO9t.pt").save("roundtrip.pt")

loaded = torch.load("roundtrip.pt", map_location="cpu", weights_only=False)
state_dict, metadata = unwrap_libreyolo_checkpoint(loaded)

print(metadata["schema_version"], metadata["model_family"])
print(metadata["size"], metadata["task"], metadata["nc"], metadata["imgsz"])
print(len(state_dict), "tensors")
```

--------------------------------

### libreyolo enroll example with folder-per-person tree

Source: https://www.libreyolo.com/docs/cli/utilities.md

Example of enrolling a face gallery from a 'people/' directory. The subfolder name becomes the identity. A reference image with no detectable face is skipped with a line on stderr; a source with no identity subfolders or no face found is an error.

```bash
# people/ holds one folder per identity; the folder name becomes the identity.
libreyolo enroll model=librefacerec-l.onnx source=people/ gallery=people.npz
```

--------------------------------

### Monitor via browser over SSH tunnel

Source: https://www.libreyolo.com/docs/train/cloud-gpus.md

Starts the LibreYOLO monitor dashboard on the box, binding to 127.0.0.1:8420 by default, then sets up an SSH port forward so you can open http://localhost:8420 locally. The monitor uses only the standard library and needs nothing beyond LibreYOLO installed.

```bash
# On the box (binds 127.0.0.1:8420 by default):
libreyolo monitor /root/runs/run1 --no-browser

# From your machine, then open http://localhost:8420 locally:
#   ssh -L 8420:localhost:8420 <user>@<host>
```

--------------------------------

### Streaming inference with stream=True

Source: https://www.libreyolo.com/docs/reference/model-api.md

Runs inference with `stream=True` to get a generator of Results objects, one per frame or image. This example passes a list of two sample images and prints the length of each result. Useful for processing large or live sources without materializing all results at once.

```python
from libreyolo import LibreYOLO, SAMPLE_IMAGE

model = LibreYOLO("LibreYOLO9t.pt")

# stream=True returns a generator, one Results per frame or image.
for result in model([SAMPLE_IMAGE, SAMPLE_IMAGE], stream=True):
    print(len(result))
```

--------------------------------

### Enroll and identify from the CLI

Source: https://www.libreyolo.com/docs/tasks/face-recognition.md

Enroll a gallery and then predict using that gallery from the command line.

```bash
libreyolo enroll model=librefacerec-l.onnx source=people/ gallery=faces.npz
libreyolo predict model=librefacerec-l.onnx source=group_photo.jpg gallery=faces.npz
```

--------------------------------

### Prerequisites for Hailo Dataflow Compiler

Source: https://www.libreyolo.com/docs/export/hailo.md

Lists the required prerequisites for the Hailo side: a Linux x86_64 machine (WSL2 Ubuntu 22.04 works), the hailo_sdk_client wheel from the Hailo Developer Zone, the Hailo Model Zoo v2.x for Hailo-8 and Hailo-8L recipes/NMS configurations, and a GPU strongly recommended because quantization can take hours without one. None are installable from PyPI.

```text
Prerequisites, none of them installable from PyPI:

- A Linux x86_64 machine. WSL2 Ubuntu 22.04 works. The Raspberry Pi is a
  runtime target, never the compile host.
- The Dataflow Compiler wheel (hailo_sdk_client) from the Hailo Developer
  Zone, which is free to register for.
- For Hailo-8 and Hailo-8L, the Hailo Model Zoo v2.x line, for its
  recipes and NMS configurations.
- A GPU on the compile host is strongly recommended: the quantization
  step takes hours without one.

```

--------------------------------

### Install TensorRT dependencies

Source: https://www.libreyolo.com/docs/export/tensorrt.md

Install the necessary packages for ONNX and TensorRT support.

```bash
pip install "libreyolo[onnx,tensorrt]"
```

--------------------------------

### Launch multi-GPU training with torchrun

Source: https://www.libreyolo.com/docs/train/multi-gpu.md

This example shows a training script written for a single device, intended to be launched with torchrun. The trainer uses cuda:LOCAL_RANK and torchrun owns the process count. Do not combine with device="0,1" when torchrun is used.

```python
from libreyolo import LibreYOLO

if __name__ == "__main__":
    model = LibreYOLO("LibreYOLO9s.pt")
    model.train(data="my-dataset.yaml", epochs=100, batch=32)
```

```bash
torchrun --nproc_per_node=2 train.py
```

--------------------------------

### libreyolo quantize synopsis

Source: https://www.libreyolo.com/docs/cli/quantize.md

Shows the command-line syntax for the quantize command. Arguments are key=value pairs, and POSIX form works too, so recipe=int8 and --recipe int8 are the same argument.

```bash
libreyolo quantize model=<name|path> [recipe=<recipe>] [key=value ...]
```

--------------------------------

### Install mss for screen capture

Source: https://www.libreyolo.com/docs/predict/sources.md

Screen capture requires the mss package. Install it with pip.

```bash
pip install mss
```

--------------------------------

### Install NNCF for INT8 quantization

Source: https://www.libreyolo.com/docs/export/openvino.md

Installs NNCF separately. NNCF is only needed when exporting with int8=True.

```bash
pip install nncf
```

--------------------------------

### Train with LoRA via CLI

Source: https://www.libreyolo.com/docs/experimental

CLI equivalent of the Python training example. Uses the --lora flag to enable LoRA fine-tuning.

```bash
libreyolo train --model rf-detr-nano.pth --data data.yaml --lora
```

--------------------------------

### Install SigLIP2 extra

Source: https://www.libreyolo.com/docs/models/siglip2.md

Installs the SigLIP2 extra, which pulls in the SentencePiece package required by its multilingual tokenizer.

```bash
pip install "libreyolo[siglip2]"
```

--------------------------------

### Install libreyolo with sensenova extra

Source: https://www.libreyolo.com/docs/models/sensenova-vision.md

Installs LibreYOLO with the sensenova extra, which pulls in accelerate for big-model dispatch and, on non-macOS platforms, bitsandbytes for 4-bit loading. The checkpoint is CC BY-NC 4.0 and downloads automatically on first use.

```bash
pip install "libreyolo[sensenova]"
```

--------------------------------

### Install Dome-DETR with pip

Source: https://www.libreyolo.com/docs/models/dome-detr.md

Dome-DETR requires no optional extra; the base LibreYOLO installation includes all its dependencies.

```bash
pip install libreyolo

```

--------------------------------

### The five entry points

Source: https://www.libreyolo.com/docs/reference/python-api.md

Shows how to import and use LibreYOLO and LibreEnsemble. The other three factories (LibreSAM, LibreVLM, LibreOpenVocab) require an extra install: pip install 'libreyolo[sam]', 'libreyolo[vlm]', or 'libreyolo[openvocab]'. LibreYOLO sniffs the checkpoint or file suffix; LibreEnsemble fuses two or more detectors.

```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)
```

--------------------------------

### Install LibreYOLO ONNX extras

Source: https://www.libreyolo.com/docs/export/hailo.md

Install the libreyolo package with the onnx extra to enable ONNX export.

```bash
pip install "libreyolo[onnx]"

```

--------------------------------

### libreyolo ui synopsis

Source: https://www.libreyolo.com/docs/cli/ui.md

Shows the command format: arguments are `key=value` pairs, and POSIX form also works (e.g., `port=9000` and `--port 9000` are equivalent).

```bash
libreyolo ui [key=value ...]
```

--------------------------------

### Install development implementation with event-histogram-input branch

Source: https://www.libreyolo.com/docs/train/event-histograms.md

Install the development version of LibreYOLO with the event-histogram-input feature branch. This is required until PR #865 is merged into dev. After merge, replace @event-histogram-input with @dev; after v1.6 release, install the corresponding PyPI version.

```bash
python -m pip install "libreyolo[rfdetr,onnx] @ git+https://github.com/LibreYOLO/libreyolo.git@event-histogram-input"
```

--------------------------------

### Assert Torch Is Not Installed (Python)

Source: https://www.libreyolo.com/docs/lightweight-install.md

Use this assertion to confirm that torch is not installed in the current environment. It is recommended for CI in the slim image to prevent false positives from a pre-installed torch. If torch is present, the assertion fails with the message 'torch is installed'.

```python
import importlib.util

assert importlib.util.find_spec("torch") is None, "torch is installed"
```

--------------------------------

### Run YOLO-NAS detection via CLI

Source: https://www.libreyolo.com/docs/models/yolo-nas.md

CLI equivalent of the Python detection example, using the model name and a sample image URL.

```bash
libreyolo predict model=LibreYOLONASs.pt save=True \
  source=https://raw.githubusercontent.com/LibreYOLO/libreyolo/release/libreyolo/assets/parkour.jpg
```
Tokens:
Raw