libreyolo train

Synopsis

libreyolo train data=<dataset.yaml> [model=<name|path>] [key=value ...]

Arguments are key=value pairs, and POSIX form works too, so epochs=50 and --epochs 50 are the same argument. Booleans accept true and false: amp=false becomes --no-amp where the flag has a negative form.

Arguments

Model and data

Training loop

Distillation

Optimizer

Scheduler

Augmentation

EMA

Validation during training

Output

Agent flags

Examples

# coco8.yaml ships with the package and downloads its 8 images on first use.libreyolo train model=LibreYOLO9s.pt data=coco8.yaml epochs=10 imgsz=640 batch=8

# Prints what the run would use, including family defaults, and exits# without training or loading data.libreyolo train model=LibreDFINEn.pt data=coco8.yaml epochs=10 dry_run=true

libreyolo train model=LibreYOLO9s.pt data=coco8.yaml \  epochs=50 batch=8 optimizer=adamw lr0=0.001 weight_decay=0.0001 \  patience=20 save_period=5 project=runs/train name=yolo9s-coco8 exist_ok=true

Notes

The defaults above are not always the values used

Every model family carries its own training config, and where that config differs from the base one, its value replaces the command default for any argument you did not set explicitly. Setting the argument yourself always wins. libreyolo cfg prints the base defaults and the per-family overrides, which is the way to see what a given family will actually use.

imgsz is the argument this matters most for. The command default is 640, which is not every checkpoint's native input: the published RF-DETR detection sizes are 384, 512, 576 and 704, and the YOLOX n and t checkpoints are 416. RF-DETR and DEIMv2 are handled by only forwarding imgsz when it was set explicitly, so their own size stays in force otherwise. Other families are handed the value as given and train at it. FOMO is the strict one: each size accepts only its native input (96, 192 and 224), so a FOMO run needs imgsz set to match or it stops with an error. RF-DETR also requires the value to divide by its patch size times its window count, and reports the two nearest legal sizes when it does not.

Arguments a family ignores

Not every family reads every argument, and the augmentation ones are where that shows. RF-DETR, D-FINE, DEIM, DEIMv2, RT-DETRv4 and DINOv2 train through pass-through pipelines with no mosaic, no mixup and no affine warp, so mosaic, mixup, hsv_prob, degrees, translate, shear, mosaic_scale and mixup_scale reach nothing there. EC shares that pipeline but does read hsv_prob, degrees and translate when its task is pose. The classification families ignore that set except mixup, which is batch MixUp for them, and they read flip_prob. SegFormer, LingBot-Vision and NAFNet ignore the whole set and flip_prob with it, because their flip runs at a fixed probability rather than a configurable one. YOLO-NAS ignores mosaic alone, since it augments with an always-on per-sample affine instead. RF-DETR ignores three more on top of that list: optimizer, momentum and nesterov.

Setting one of these is not an error. The run logs a line to stderr naming the family and the arguments it will ignore, then trains, and that line is the authoritative list for the version installed. It is also the only signal, so a scripted run with quiet=true suppresses the warning along with everything else on stderr.

val=false is a related case. It sets eval_interval to 0, which turns validation during training off, final epoch included, and the run writes no best.pt.

Other behavior worth knowing

lora=true is accepted by RF-DETR, D-FINE, DEIM, DEIMv2, RT-DETR v1, v2 and v4, EC, GTR and ConvNeXt. Any other family exits with config_unsupported rather than training without it.

clip_max_norm is accepted by the families whose training config declares it: YOLOv9, YOLOv9-E2E and YOLOv9-P2, where it defaults to 10, and D-FINE, Dome-DETR, DEIM, DEIMv2, TinyFormer, RT-DETR, RT-DETRv2, RT-DETRv4, RF-DETR, DINOv2 and GTR, where it defaults to 0.1. Any other family exits with config_unsupported, and a negative or non-finite value exits with config_type_error.

device=0,1 builds the model on the first listed GPU and passes the list to train(), which starts one process per GPU. See multi-GPU training.

RF-DETR has no detect-to-segment transfer. task=segment with an RF-DETR segment checkpoint loads that checkpoint whatever its filename, because the checkpoint metadata decides the task, while a detection checkpoint stops with an error instead of training an untrained mask head.

pretrained=false combined with resume is refused for the families that support scratch training, since the two ask for opposite things.

mosaic and mixup are the command-line spellings of the mosaic_prob and mixup_prob config fields; on a classification model mixup is batch MixUp instead. On families whose mixup only applies to mosaic samples, mixup above zero with mosaic at zero never fires, and the run says so.

dry_run=true resolves the model reference, applies family defaults, and prints the config it would train with. It does not load the dataset, so it is the cheap way to confirm an argument reached the value you expected.

stdout carries the final result object; progress and warnings go to stderr. The exit code is 0 on success, 2 for a usage or configuration error, 3 when the dataset cannot be found or read, 4 when the model cannot be loaded, and 1 for other runtime failures.

Related: libreyolo doctor to check a dataset before committing to a run, libreyolo monitor to watch a run in the browser, libreyolo val to measure the result.