Ultralytics YOLO

Warnings

• breaking The v8 release introduced a complete API overhaul. The primary interaction shifted from direct script execution or specific task imports (e.g., `detect.py`) to a unified `YOLO` class interface. Code written for v7 or earlier versions is not directly compatible.
  Fix: Refactor code to use the `from ultralytics import YOLO` and the `model = YOLO('model.pt')` interface for all tasks (train, predict, export, val).
• gotcha Training resume functionality has historically been prone to issues (e.g., not restoring optimizer state, incorrect argument loading). While recent patch releases (v8.4.29-v8.4.36) include numerous fixes, users should verify resume behavior, especially after major dependency updates or unexpected interruptions.
  Fix: Always test `resume=True` thoroughly. Ensure `last.pt` (or specified checkpoint) contains complete training state. Consider using `last_good.pt` for recovery if `last.pt` gets corrupted.
• gotcha Optimal performance requires a correctly configured GPU environment (CUDA, cuDNN, PyTorch with CUDA support). Without it, Ultralytics will silently fall back to CPU, leading to significantly slower training and inference.
  Fix: Verify `torch.cuda.is_available()` returns `True`. Ensure your PyTorch installation matches your CUDA toolkit version. Install `ultralytics` with `pip install ultralytics[all]` to include necessary GPU-related dependencies or ensure a compatible PyTorch version is installed separately.
• gotcha Data preparation (dataset YAMLs, annotation formats) is crucial. Incorrect paths, missing files, or malformed annotation files (especially COCO JSON or YOLO TXT) are common sources of errors during training or validation.
  Fix: Carefully review the official Ultralytics documentation for expected dataset structures and YAML configurations. Use `model.val()` with a small subset of your data to quickly check dataset integrity before full training.
• gotcha Training can occasionally encounter 'NaN' losses, especially with aggressive learning rates, mixed precision (FP16), or problematic data. Recent versions include improvements for NaN recovery but it remains a potential issue.
  Fix: If 'NaN' losses occur, try reducing the learning rate, increasing `warmup_epochs`, disabling `half` precision, cleaning your dataset for corrupted images/annotations, or inspecting the model's intermediate activations for instability.

Install

• pip install ultralytics Stable release
• pip install ultralytics[all] With all dependencies (e.g., for segmentation, tracking)

Imports

• YOLO

  from ultralytics import YOLO

  Prior to v8, users often imported specific task predictors directly or ran scripts. The `YOLO` class is now the primary, unified interface for all tasks (detect, segment, classify, pose, track).

Quickstart

This quickstart demonstrates loading a pretrained YOLOv8 nano model, performing inference on an image, and exporting the model to ONNX format. While training is commented out for brevity, the `model.train()` method is the standard way to fine-tune or train models from scratch.

from ultralytics import YOLO
import os

# Load a pretrained YOLOv8n model
model = YOLO('yolov8n.pt')

# Use the model for training (example with dummy data for brevity)
# For a real run, ensure 'coco128.yaml' or your custom data path is valid
# You might need to download a dataset like coco128 first.
# For a quick local test, you can uncomment and try to train on a tiny dataset:
# try:
#     results = model.train(data='coco128.yaml', epochs=1, imgsz=640)
# except Exception as e:
#     print(f"Training failed (might be missing dataset or GPU): {e}")

# Use the model for prediction on an image
image_path = 'https://ultralytics.com/images/bus.jpg'
results = model(image_path)

# Process results
for r in results:
    print(f"Detected {len(r.boxes)} objects.")
    # r.show()  # Uncomment to display the image with detections

# Export the model to ONNX format
model.export(format='onnx')