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.

Command: libreyolo predict
Required: source
Output: Predictions on stdout. With save=true, annotated files under runs/detect/predict

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
`agnostic_nms`	`false`	Class-agnostic NMS: among boxes overlapping above `iou`, keep only the highest-scoring one whatever their classes. Detect, segment, pose and OBB
`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

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

Save annotated images

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

# 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 for measured metrics on a dataset, libreyolo export to produce the runtime artifacts named above.