yolo-training

Training & fine-tuning

Fastest route: train in Platform

Use Platform cloud training when you want to start in a few clicks without configuring a local GPU:

1. Click New Model on a project page, or on a dataset page to preselect that dataset.
2. Select a compatible pretrained model, ready dataset, GPU, epochs, image size, and batch size.
3. Click Start Training and watch live charts, console logs, and system metrics.
4. Open the completed model to inspect validation plots and use its Predict, Export, or Deploy tab. Platform preserves best.pt automatically.

Cloud jobs require at least one train image, one val/test image, and one labeled image. Use local/Colab training when you already have compute or need more control, while keeping Platform datasets and experiment tracking:

export ULTRALYTICS_API_KEY="YOUR_API_KEY"
yolo train model=yolo26n.pt data=ul://username/datasets/dataset-slug \
  epochs=100 project=username/project-slug name=experiment-1

With ultralytics>=8.4.120 on Python 3.11+, the ul:// URI downloads the Platform dataset, and while an API key is available (ULTRALYTICS_API_KEY or the api_key setting), any project= value — even a local folder — streams metrics and uploads weights to Platform. Omit project to keep a run local; a list data= sets it internally, so unset the key for those runs.

Quickstart (detection)

from ultralytics import YOLO

model = YOLO("yolo26n.pt")  # ALWAYS start from pretrained weights
results = model.train(data="data.yaml", epochs=100, imgsz=640, batch=16, device=0)

yolo detect train data=data.yaml model=yolo26n.pt epochs=100 imgsz=640 batch=16 device=0

Class-count changes are automatic — a 3-class data.yaml on an 80-class pretrained model just works (head re-initializes, backbone transfers; cls_remap=True even re-maps head rows for classes whose names match).

Base arguments worth setting (task trainers can override them)

Arg	Default	Notes
epochs	100	100–300 for fine-tuning; rely on early stopping, not guesses
patience	100	epochs without val improvement before early stop; ~20–50 for quick iterations
imgsz	task/model	global fallback 640; classify uses 224 when unset; explicit values win
batch	16	-1 auto-fits ~60% VRAM (single GPU); float like 0.8 = VRAM fraction; else integer
device	None	0, [0,1] (DDP), cpu, mps, -1 picks an idle GPU
cache	False	True (RAM) or "disk" for I/O-bound training
workers	8	lower if RAM/shared-memory errors
freeze	None	freeze first N layers (freeze=10 ≈ backbone) for small datasets
optimizer	auto	leave on auto (MuSGD above 10k iterations, else AdamW); depth fine-tuning overrides it below
lr0 / lrf	0.01 / 0.01	lr0 ignored by optimizer=auto; set an explicit optimizer to use it (see depth recipe)
fraction	1.0	subset training — fraction=0.1 for smoke tests
resume	False	continue an interrupted run (see recipes)
project/name	None	output folder: relative project → runs/<task>/<project>/<name>, absolute → <project>/<name>. With an API key available on Python 3.11+, any project uploads to Platform
seed	0	reproducible with deterministic=True (default)
compile	False	torch.compile; also "max-autotune-no-cudagraphs" etc.
time	None	max training hours — overrides epochs

Full argument, augmentation, and loss-weight tables: training-args.md (this folder) — read before changing anything not listed above. yolo cfg shows the base schema and defaults; task trainers, checkpoints, and explicit arguments determine effective values.

Recipes

• Resume interrupted run: YOLO("runs/detect/train/weights/last.pt").train(resume=True). Resume finishes the original epochs; to train longer after completion, start a NEW training from best.pt (resume can't extend a finished run).
• Multi-GPU: device=[0,1] with an integer batch (AutoBatch is single-GPU only). DDP workers rebuild from a generated script that cloudpickles the trainer, model, and callbacks; official Windows PyTorch>=2.4 wheels can't launch DDP, so use Linux or WSL2.
• Small detect-style dataset (<~1k images): pretrained + freeze=10, n/s model, default augmentation, watch val curves.
• Depth fine-tuning: start from -depth.pt and use optimizer=AdamW lr0=1e-4 warmup_bias_lr=1e-4.
• Small objects: try imgsz=1280 (more compute/VRAM; reduce batch if needed), or tile large images at dataset level.
• Experiment hygiene: self-describing run names (name=0811_yolo26s_helmets_e100), one variable per run; each run's full config is saved in runs/<task>/<name>/args.yaml — diff those to compare runs.
• Logging integrations: yolo settings tensorboard=True (likewise wandb), then train normally. mlflow, comet, and clearml are on by default and activate once their package is installed.
• Knowledge distillation: distill_model=yolo26l.pt dis=6.0 trains the student with a larger teacher.

Validation

yolo val model=runs/detect/train/weights/best.pt data=data.yaml # split=val by default

Per-task headline metrics: detect/obb mAP50-95(B), segment (M), pose (P), semantic mIoU, depth delta1, classify accuracy_top1. Val base defaults are conf=0.001 (0.01 for OBB), iou=0.7, and nms=None (one-to-many head + NMS); nms=False validates YOLO26's NMS-free head, where iou is inactive. Use split=test for the test set and save_json=True for COCO-format eval.

Reading a finished run (runs/<task>/<name>/)

• weights/best.pt — highest val fitness; use this one. last.pt — for resuming.
• results.csv / results.png — per-epoch losses and val metrics. Interpretation: train loss ↓ while val mAP plateaus-then-drops = overfitting (more data/aug, smaller model — best.pt already kept the good checkpoint). Both flat and low = underfitting (bigger model, more epochs, higher imgsz, check labels). mAP50 good but mAP50-95 poor = sloppy localization (higher imgsz, better boxes).
• train_batch*.jpg — augmented images with labels drawn. Look once per project: wrong labels are instantly visible here.
• confusion_matrix.png — off-diagonal cluster between two classes = inconsistent labels or genuinely similar classes. Axes are predicted (y) × true (x): heavy background row = missed detections (that class needs more/better examples); heavy background column = false positives (add background images or raise conf at inference).

Troubleshooting

Symptom	Fix, in order
CUDA out of memory	lower batch (or batch=-1), lower imgsz, smaller model; kill zombie python processes holding VRAM
NaN / exploding loss	set optimizer=AdamW lr0=0.001 (auto ignores lr0); check labels; try amp=False
mAP near 0	dataset problem 95% of the time — see yolo-datasets, check train_batch*.jpg
mAP plateaus low	more/better data first; then imgsz ↑, bigger model, more epochs; see yolo-tuning playbook
Stopped earlier than expected	that's patience — raise it or accept best.pt
Dataloader slow / GPU idle	cache=True/"disk", raise workers, data on SSD
Val metrics zero mid-run	classes missing from the val split

Anti-patterns: pretrained=False "to train properly" (needs ~100× more data); benchmarking model sizes on 50 images; copying 30-argument commands (start from defaults); tuning hyperparameters while the confusion matrix screams label noise.

Related pages

• training-args.md — full train/augmentation/loss-weight argument tables. Read before setting any argument not in the table above.

If the installed version rejects an argument (yolo checks shows the version), trust the error text and yolo cfg over this file.