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

# libreyolo train
Trains one model on one dataset and writes checkpoints, metrics and logs into a run directory. Every argument below has a default from the command definition, which a model family's own training config may replace.
Verified against LibreYOLO v1.6.0.

## Synopsis

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

| Argument | Default | Meaning |
|---|---|---|
| `data` | | Path to dataset YAML (YOLO format, e.g. `coco8.yaml`). Required |
| `model` | `yolox-s` | Model name or path to weights |
| `task` | | Explicit task override: `detect`, `segment`, `semantic`, `pose`, `classify`, `gaze`, `obb`, `point`, `depth` |
| `pretrained` | `true` | Use pretrained weights. `false` builds the architecture and trains from scratch |
| `allow_download_scripts` | `false` | Allow embedded Python in dataset YAML download blocks |

### Training loop

| Argument | Default | Meaning |
|---|---|---|
| `epochs` | `300` | Training epochs |
| `batch` | `16` | Batch size per device |
| `imgsz` | `640` | Training image size: `640` (square) or `480x640` (HxW) |
| `device` | `auto` | Device: `0`, `cpu`, `mps`, `auto` |
| `workers` | `4` | Dataloader workers |
| `cache` | `false` | Cache images to speed dataloading: `ram`, `disk`, `true`, `false` |
| `seed` | `0` | Random seed |
| `resume` | | Resume training: `true`, or a path to a checkpoint |
| `amp` | `true` | Automatic Mixed Precision |
| `amp_dtype` | `float16` | CUDA AMP dtype: `float16` or `bfloat16` |
| `cuda_graph` | `false` | Capture the training forward and backward into CUDA graphs. Single GPU, supported families only; the rest run eager |
| `compile` | `false` | `torch.compile` the training network: `true`, `false`, `default`, `reduce-overhead`, `max-autotune`, `max-autotune-no-cudagraphs`. Single CUDA GPU; other runs train eager with a warning |
| `lora` | `false` | LoRA fine-tuning, for the transformer families listed under Notes |
| `freeze` | | Freeze layers: an integer count, a list of indices, or module names |

### Distillation

| Argument | Default | Meaning |
|---|---|---|
| `distill_model` | | Teacher: a detector checkpoint, or a foundation-teacher id such as `dinov2` for backbone feature distillation |
| `dis` | | Distillation loss weight. The published default for the loss type when unset |
| `distill_loss_type` | `mgd` | Feature loss for detector teachers: `mgd`, `cwd`. Foundation teachers always use `feat_mse` |

### Optimizer

| Argument | Default | Meaning |
|---|---|---|
| `optimizer` | `sgd` | Optimizer: `sgd`, `adam`, `adamw` |
| `lr0` | `0.01` | Initial learning rate |
| `momentum` | `0.937` | SGD momentum, and the first-moment coefficient for the Adam optimizers |
| `weight_decay` | `0.0005` | L2 regularization |
| `nesterov` | `true` | Nesterov momentum |

### Scheduler

| Argument | Default | Meaning |
|---|---|---|
| `scheduler` | `yoloxwarmcos` | LR schedule type |
| `warmup_epochs` | `5` | Warmup duration |
| `warmup_lr_start` | `0.0` | Initial warmup LR |
| `min_lr_ratio` | `0.05` | Minimum LR ratio |
| `lr_drop` | `100` | RF-DETR step LR drop epoch |

### Augmentation

| Argument | Default | Meaning |
|---|---|---|
| `mosaic` | `1.0` | Mosaic probability |
| `mixup` | `1.0` | Mixup probability |
| `hsv_prob` | `1.0` | HSV jitter probability |
| `flip_prob` | `0.5` | Horizontal flip probability |
| `degrees` | `10.0` | Rotation range, plus and minus, in degrees |
| `translate` | `0.1` | Translation ratio |
| `shear` | `2.0` | Shear angle |
| `mosaic_scale` | `(0.1,2.0)` | Mosaic scale range |
| `mixup_scale` | `(0.5,1.5)` | Mixup scale range |
| `no_aug_epochs` | `15` | Disable augmentation for the final N epochs |

### EMA

| Argument | Default | Meaning |
|---|---|---|
| `ema` | `true` | Exponential Moving Average |
| `ema_decay` | `0.9998` | EMA decay factor |

### Validation during training

| Argument | Default | Meaning |
|---|---|---|
| `val` | `true` | Validate during training |
| `eval_interval` | `10` | Validate every N epochs, and after the final epoch |
| `max_det` | `300` | Maximum predictions per image after validation NMS |
| `eval_max_det` | | COCO evaluator cap. The pycocotools AP@100 convention when unset |
| `faster_coco_eval` | `true` | Use the faster-coco-eval C++ backend for COCO metrics when installed; falls back to pycocotools |
| `save_plots` | `false` | Save final validation plots during training |
| `patience` | `50` | Early stopping patience. `0` disables it |

### Output

| Argument | Default | Meaning |
|---|---|---|
| `project` | `runs/train` | Output directory root |
| `name` | `exp` | Experiment name |
| `exist_ok` | `false` | Reuse existing output directory |
| `save_period` | `10` | Save checkpoint every N epochs |
| `log_interval` | `10` | Log loss every N batches |

### Agent flags

| Argument | Default | Meaning |
|---|---|---|
| `json` | `false` | JSON output to stdout |
| `quiet` | `false` | Suppress stderr |
| `dry_run` | `false` | Resolve and print the config without executing |
| `help_json` | `false` | Dump command schema as JSON and exit |

| Argument | Default | Meaning |
| --- | --- | --- |
| `min_samples` | `0` | Epoch-length floor for tiny datasets: when the dataset has fewer images, draw this many samples per epoch with replacement (0 = off) |
| `class_balanced` | `False` | LVIS-style repeat-factor sampling for long-tailed datasets (default: off) |
| `cls_pw` | `0.0` | Classification inverse-frequency weighting power: 0 off, 1 full (mean-one class weights; cannot combine with class_weights=True) |
| `class_weights` | `False` | Legacy sample-normalized classification loss weights (default: off) |
| `single_cls` | `False` | Train a supported detector with every label remapped to class 0 |
| `classes` | `None` | Train a supported detector on only these original dataset class ids, comma-separated (e.g. '0,3,5'); every other class is dropped as if unlabeled. Ids are kept as-is, not compacted |
| `average_best` | `0` | Uniform-average the N best checkpoints by the watched metric into weights/average.pt at the end of training (0 = off) |
| `export_check` | `False` | Export ONNX before epoch 1 and fail the run if export breaks (default: off) |
| `precise_bn` | `0` | Recompute BatchNorm running stats from this many train images after the last epoch (0 = off) |
| `aux_weight` | | YOLO9 only: PGI auxiliary-branch loss weight for fine-tuning. `0.25` when unset; `0` trains the main head only |
| `fliplr` | `None` | Horizontal flip probability (ecosystem alias of flip_prob) |
| `flipud` | `0.0` | Vertical flip probability |
| `auto_augment` | `None` | Classification auto-augment policy: randaugment, autoaugment, augmix (default: none) |
| `erasing` | `0.0` | Classification RandomErasing probability, 0 <= erasing < 1 |
| `cutmix` | `0.0` | Classification CutMix probability (soft labels) |
| `scale` | `0.5` | Classification RandomResizedCrop area range: a float lower bound or an explicit (min,max) |
| `crop_pct` | `None` | Classification eval resize ratio before the center crop (default: the model family's native value) |
| `plot_samples` | `8` | Sample images in the validation sample plot: 0 for none, -1 for every validated image (does not change the metrics) |

## Examples

**Basic**

```bash
# 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
```

**Check the resolved config first**

```bash
# 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
```

**Named run with an explicit recipe**

```bash
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 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.

`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`](/docs/v1.6.0/cli/doctor) to check a dataset before
committing to a run, [`libreyolo monitor`](/docs/v1.6.0/cli/monitor) to watch a run in
the browser, [`libreyolo val`](/docs/v1.6.0/cli/val) to measure the result.