> This is the documentation for LibreYOLO 1.6.0. Current version: https://www.libreyolo.com/docs/cli/predict

# libreyolo predict
Runs a loaded model over one source and prints the predictions. The source may be an image, a directory, a video, a URL or a live stream; the model may be a checkpoint or an exported artifact.
Verified against LibreYOLO v1.6.0.

## Synopsis

```bash
libreyolo predict source=<path|url|index> [model=<name|path>] [key=value ...]
```

Arguments are `key=value` pairs. The same command also accepts POSIX form, so
`conf=0.4` and `--conf 0.4` are interchangeable, and a boolean written
`save=true` becomes `--save`. Names with an underscore accept either spelling:
`max_det=50` and `--max-det 50` reach the same option.

`libreyolo detect predict ...` is accepted and behaves identically; the task
word is stripped before parsing.

## Arguments

| Argument | Default | Meaning |
|---|---|---|
| `source` | | Image path, directory, or URL. Required |
| `model` | `yolox-s` | Model name or path |
| `conf` | `0.25` | Confidence threshold |
| `iou` | `0.45` | NMS IoU threshold |
| `imgsz` | | Input image size: `640` (square) or `480x640` (HxW). The model's own input size when unset |
| `classes` | | Filter by class IDs, e.g. `[0,2,5]`. A bare integer is accepted |
| `max_det` | `300` | Max detections per image |
| `half` | `false` | FP16 inference (CUDA only, requires model support) |
| `save` | `false` | Save annotated images |
| `batch` | `1` | Images per forward pass for directory sources. Above 1 runs true batched inference on models that support it |
| `stream` | `false` | Yield results incrementally. Turned on automatically for webcams and live streams |
| `stream_buffer` | `false` | Buffer every live frame instead of keeping only the newest |
| `vid_stride` | `1` | Process every N-th video or live frame |
| `show` | `false` | Display video and live results; `q` stops |
| `tiling` | `false` | Tiled inference for large images |
| `overlap_ratio` | `0.2` | Tile overlap ratio |
| `output_path` | | Explicit output path. Otherwise `project/name` when `save=true` |
| `color_format` | `auto` | Input color: `auto`, `rgb`, `bgr` |
| `output_file_format` | | Output format: `jpg`, `png`, `webp` |
| `device` | `auto` | Device: `0`, `cpu`, `mps`, `auto` |
| `face_detector` | | Face detector model (path or CLI name). Required for gaze models |
| `gallery` | | Face gallery `.npz` from `libreyolo enroll` to identify faces against. Face-embedding models only |
| `gallery_threshold` | `0.4` | Cosine threshold for a gallery identity match |
| `project` | `runs/detect` | Output directory root |
| `name` | `predict` | Experiment name |
| `exist_ok` | `false` | Reuse existing output directory |
| `json` | `false` | JSON output to stdout |
| `quiet` | `false` | Suppress stderr |
| `verbose` | `false` | Verbose stderr output |
| `help_json` | `false` | Dump command schema as JSON and exit |

| Argument | Default | Meaning |
| --- | --- | --- |
| `mask` | `None` | Single-image binary inpainting mask for models that require it |
| `trimap` | `None` | Single-image three-level trimap for guided matting models |

## Examples

**Basic**

```bash
libreyolo predict model=LibreYOLO9s.pt \
  source=https://raw.githubusercontent.com/LibreYOLO/libreyolo/release/libreyolo/assets/parkour.jpg
```

**Save annotated images**

```bash
libreyolo predict model=LibreYOLO9s.pt save=true \
  project=runs/detect name=parkour exist_ok=true \
  source=https://raw.githubusercontent.com/LibreYOLO/libreyolo/release/libreyolo/assets/parkour.jpg
```

**Filtered classes, JSON on stdout**

```bash
# class 0 is person in the COCO class list the checkpoint ships with.
libreyolo predict model=LibreYOLO9s.pt classes="[0]" conf=0.4 max_det=50 \
  json=true quiet=true \
  source=https://raw.githubusercontent.com/LibreYOLO/libreyolo/release/libreyolo/assets/parkour.jpg
```

## Notes

An exported artifact loads the same way a checkpoint does, so
`model=weights/LibreYOLO9s.onnx` and `model=weights/LibreYOLO9s.engine` are
valid values for `model`. Three options are refused on those runtimes rather
than ignored: `tiling`, `overlap_ratio` and `output_file_format` exit with
`config_unsupported` when a runtime backend cannot honor them.

`half` goes the other way: it is accepted and ignored. Native PyTorch inference
logs that it was ignored and continues in FP32, and an exported runtime keeps the
precision it was exported with, so FP16 inference means exporting with `half=true`.

Gaze models are two stage and have no detector of their own, so
`face_detector` is required for them. `gallery` applies only to models whose
task is `embed`; passing it to anything else exits with `config_unsupported`.

stdout carries results and nothing else; progress, warnings and errors go to
stderr. `json=true` prints one JSON object per invocation, or one per frame
when streaming, each carrying `schema_version`. `quiet=true` silences stderr.
Both together give a machine reader a clean stdout stream.

The exit code is `0` on success, `2` for a usage or configuration error, `3`
when the source cannot be found, `4` when the model cannot be loaded, and `1`
for other runtime failures.

`help_json=true` prints the command's parameters, types, defaults and flags as
JSON without running anything, which is the reliable way to read this table
back from an installed version.

Related: [`libreyolo val`](/docs/v1.6.0/cli/val) for measured metrics on a dataset,
[`libreyolo export`](/docs/v1.6.0/cli/export) to produce the runtime artifacts named
above.