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. Create a project and click New Model (or start from a dataset's Train action).
2. Select a compatible pretrained model, ready dataset, GPU, epochs, image size, and

batch size.

1. Click Start Training and watch live charts, console logs, and system metrics.
2. 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, the ul:// URI downloads the Platform dataset and the username/project-slug target streams metrics back to that Platform project.

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)

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]. Run as a script — DDP spawns processes and breaks in

notebooks (and on Windows, guard with if name == "main":).

• 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 warmupbiaslr=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=0811yolo26shelmets_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,

mlflow, comet, clearml) — then train normally.

• 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 accuracytop1. Val base defaults are conf=0.001 (0.01 for OBB) and iou=0.7; iou is inactive for default end-to-end YOLO26. Use split=test for the test set and savejson=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

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 cfg and the error text are the truth, not this file (yolo checks shows the version).