> This is the documentation for LibreYOLO 1.5.0. Current version: https://www.libreyolo.com/docs/quickstart

# Quickstart
The shortest path through LibreYOLO: predict on one image, train on a small dataset, then export the result. Every command here runs on CPU.
Verified against LibreYOLO v1.5.0.

## Install

```bash
pip install libreyolo
```

That is everything the predict and train sections below need. Export to ONNX
adds one extra; see [install](/docs/v1.5.0/install) for the full list.

## Predict

**Python**

```python
from libreyolo import LibreYOLO, SAMPLE_IMAGE

# Downloads the checkpoint on first use, then caches it in weights/.
model = LibreYOLO("LibreYOLO9t.pt")

# A single image returns one Results object.
result = model(SAMPLE_IMAGE, save=True)

for box in result.boxes:
    print(result.names[int(box.cls)], float(box.conf), box.xyxy.tolist())
```

**CLI**

```bash
libreyolo predict model=yolo9-t save=True \
  source=https://raw.githubusercontent.com/LibreYOLO/libreyolo/release/libreyolo/assets/parkour.jpg
```

**Video and streams**

```python
from libreyolo import LibreYOLO

model = LibreYOLO("LibreYOLO9t.pt")

# stream=True yields one Results per frame instead of building a list.
# Replace the path with a webcam index, an RTSP URL or a folder.
for result in model.predict("clip.mp4", stream=True, save=True):
    print(len(result.boxes))
```

`LibreYOLO()` is a factory. It reads the file, works out which family the weights
belong to, and returns that family's model, so swapping in a different detector
is a one-line change. Passing `LibreYOLO9t.pt` with no directory looks for
`weights/LibreYOLO9t.pt` relative to the working directory and downloads it
there when it is missing. See [checkpoints and weights](/docs/v1.5.0/weights) for the
download rules and how to work offline.

`save=True` writes an annotated copy under `runs/detect/`, into a `predict`
directory that increments per run. The returned `Results` carries `boxes`, and
`names` maps a class index to its label. A single image path returns one
`Results`; a directory, a list of images or `stream=True` returns a list or a
generator of them.

## Train

**Python**

```python
from libreyolo import LibreYOLO

model = LibreYOLO("LibreYOLO9t.pt")

# coco8 is an 8-image dataset bundled with the library. It downloads
# from a URL on first use, so no script has to be executed.
results = model.train(
    data="coco8.yaml",
    epochs=1,
    imgsz=640,
    batch=4,
    device="cpu",
)

print(results["save_dir"])
print(results["best_checkpoint"])
```

**CLI**

```bash
libreyolo train model=yolo9-t data=coco8.yaml \
  epochs=1 imgsz=640 batch=4 device=cpu
```

**Validate**

```python
from libreyolo import LibreYOLO

model = LibreYOLO("LibreYOLO9t.pt")

# val() returns a plain dict, not an object.
metrics = model.val(data="coco8.yaml", device="cpu")

print(metrics["metrics/mAP50-95"])
print(metrics["metrics/mAP50"])
print(metrics["metrics/precision"], metrics["metrics/recall"])
```

`data` is a dataset YAML. `coco8.yaml` ships with the library, which is why the
snippet runs as pasted; a name that is not bundled is read as a path. Datasets
resolve under `~/datasets`, or under `LIBREYOLO_DATASETS_DIR` when that variable
is set.

A run writes to `project/name`, defaulting to a directory below `runs/train`,
with `weights/best.pt` and `weights/last.pt` inside it. `train()` returns a
dictionary that includes `save_dir`, `best_checkpoint`, `last_checkpoint`,
per-epoch losses and per-epoch validation metrics. The trained checkpoint loads
through `LibreYOLO()` exactly like the pretrained one.

Not every family is trainable. Where a family ships inference only, `train()`
raises `NotImplementedError` and says so. [Core concepts](/docs/v1.5.0/concepts)
explains which support tier means what.

## Export

**TorchScript**

```python
from libreyolo import LibreYOLO, SAMPLE_IMAGE

model = LibreYOLO("LibreYOLO9t.pt")

# export() returns the path it wrote.
path = model.export(format="torchscript")
print(path)

# The factory routes on file suffix, so the artifact loads back like a
# checkpoint and returns the same Results object.
exported = LibreYOLO(path)
result = exported(SAMPLE_IMAGE)
print(len(result.boxes))
```

**ONNX**

```bash
pip install "libreyolo[onnx]"
libreyolo export model=yolo9-t format=onnx imgsz=640
```

TorchScript needs nothing beyond the base install. The other targets each have
their own extra, and coverage is per family and per task rather than uniform:
see [export and deploy](/docs/v1.5.0/export).

Arguments accepted by every format include `imgsz` (an int, or a height and
width pair), `batch` (default 1), `half`, `int8` with a `data` YAML for
calibration, `dynamic` (default True), `simplify` (default True), `opset`,
`device` and `output_path`. When `output_path` is omitted the file is written
under `weights/` with a name derived from the checkpoint.

## Where to go next

- [Core concepts](/docs/v1.5.0/concepts) for tasks, families, sizes and checkpoint names.
- [Checkpoints and weights](/docs/v1.5.0/weights) for auto-download, offline use and loading safety.
- [Import existing weights](/docs/v1.5.0/migrate) if you already have a checkpoint from an upstream project.
- [All models](/docs/v1.5.0/models) for the family that fits your problem.
- [Train](/docs/v1.5.0/train), [Predict](/docs/v1.5.0/predict) and [Export](/docs/v1.5.0/export) for the full workflows.