Configuration

YOLOmatic writes YAML configs under configs/. The generated file captures:

• Model family, variant, and task
• Dataset path and annotation format
• Image size, batch size, epochs, workers, and device
• Trainer-specific options for Ultralytics, RF-DETR, SAM 3.1, or Detectron2
• Optional ClearML, TensorBoard, Roboflow, export, and resume settings

---

Training Config Example

A generated YOLO training config looks like this:

# Generated by YOLOmatic
family: YOLO26
model: yolo26n
task: detect
dataset: datasets/my_dataset/data.yaml

training:
  epochs: 150
  patience: 50
  batch: -1
  imgsz: 640
  device: "0"
  workers: 8
  cache: false
  optimizer: auto
  lr0: 0.01
  lrf: 0.01
  momentum: 0.937
  weight_decay: 0.0005
  warmup_epochs: 3.0
  amp: true
  pretrained: true
  seed: 0
  plots: true

roboflow:
  upload: false
  weight: best.pt

training.cache accepts false, true, or ram. Legacy disk values are changed to false at runtime, and matching dataset-local .npy image caches are removed before training.

To start training from a saved config:

uv run yolomatic-train

If multiple configs exist in configs/, a TUI selector appears.

---

Device Selection

CUDA is preferred when available. Apple Silicon MPS and CPU fallbacks are supported. If CUDA is requested but PyTorch cannot use it, the preflight flow offers repair guidance before training starts.

Device Value	Hardware
"0"	First NVIDIA GPU
"0,1"	Multi-GPU (GPU 0 and 1)
"cpu"	CPU (slow; for debugging)
"mps"	Apple Silicon (M1/M2/M3)
"cuda"	Any available CUDA GPU

---

Fine-Tuning

Fine-tuning configs bind a discovered checkpoint to a new dataset and generate a fresh training YAML. Checkpoint formats by trainer:

Trainer	Checkpoint Format
Ultralytics YOLO	.pt
RF-DETR	.pth
SAM 3.1	HuggingFace model ID or local artifact
Detectron2	.pth

Fine-tuning passes the checkpoint as pretrain_weights (RF-DETR) or as the model field (YOLO). Resume workflows pass the checkpoint as resume so the optimizer state is restored.

---

ClearML Block

Add a clearml block to your training YAML to override global ClearML settings for a specific run:

clearml:
  enabled: true
  project_name: "MyProject/YOLO26"
  task_name: "experiment-01"
  upload_final_model: true
  log_hyperparameters: true

---

Roboflow Block

Add a roboflow block to enable automatic post-training upload:

roboflow:
  upload: true
  weight: best.pt

Credentials (ROBOFLOW_API_KEY, ROBOFLOW_WORKSPACE, ROBOFLOW_PROJECT_IDS) must be present in .env or the shell environment for auto-upload to succeed without a prompt.

---

Global Settings

YOLOmatic also reads a persistent global settings file at configs/yolomatic_settings.yaml. This file controls defaults for ClearML, Roboflow, dataset paths, TUI verbosity, and AI provider credentials. Training configs take precedence over global settings for keys they define.

See Settings File Reference for the full key-by-key reference.

Related pages: Settings File, First training run, RF-DETR, Cloud upload.