Ultralytics

The unified API behind YOLOv8 and YOLO11. Ultralytics gives you one consistent interface for detection, instance segmentation, classification, pose estimation, and OBB (oriented bounding boxes) — plus built-in export to ONNX, TensorRT, CoreML, and more. If you're deploying a vision model, you'll end up here.

Table of Contents

• Installation / Setup
• Core Syntax
• Common Operations
• Practical Examples
• Common Patterns
• Best Practices
• Common Mistakes
• Troubleshooting
• Related Cheat Sheets
• Official Documentation

Installation / Setup

pip install ultralytics              # or: uv add ultralytics

Key task types:

Task	Model prefix	Output	Example model
Detection	yolo11?	Bounding boxes + classes	yolo11n.pt
Segmentation	yolo11?-seg	Masks + boxes + classes	yolo11n-seg.pt
Classification	yolo11?-cls	Class label	yolo11n-cls.pt
Pose estimation	yolo11?-pose	Keypoints + boxes	yolo11n-pose.pt
OBB (oriented)	yolo11?-obb	Oriented boxes	yolo11n-obb.pt

All models follow the same API — just change the model file.

Core Syntax

Python API

from ultralytics import YOLO

# load any task model
model = YOLO("yolo11n.pt")          # detection
model = YOLO("yolo11n-seg.pt")      # segmentation
model = YOLO("yolo11n-cls.pt")      # classification
model = YOLO("yolo11n-pose.pt")     # pose

# predict
results = model("image.jpg", conf=0.5, imgsz=640)

# train
model.train(data="dataset.yaml", epochs=100, imgsz=640)

# validate
metrics = model.val()

# export
model.export(format="onnx")

CLI

# detection inference
yolo detect predict model=yolo11n.pt source="image.jpg" conf=0.5

# training
yolo detect train data=dataset.yaml epochs=100 imgsz=640

# validation
yolo detect val model=best.pt data=dataset.yaml

# export
yolo export model=yolo11n.pt format=onnx

# segmentation
yolo segment predict model=yolo11n-seg.pt source="image.jpg"

# classification
yolo classify predict model=yolo11n-cls.pt source="image.jpg"

# pose
yolo pose predict model=yolo11n-pose.pt source="image.jpg"

CLI command	Purpose
yolo detect predict	Run detection inference
yolo segment predict	Run segmentation inference
yolo classify predict	Run classification inference
yolo pose predict	Run pose estimation
yolo detect train	Train a detection model
yolo detect val	Validate a trained model
yolo export	Export to deployment format

Common Operations

Inference — programmatically extract results

from ultralytics import YOLO

model = YOLO("yolo11n.pt")
results = model("street.jpg", conf=0.5)

for r in results:
    # detection boxes
    for box in r.boxes:
        xyxy = box.xyxy[0].tolist()
        conf = box.conf[0].item()
        cls = int(box.cls[0].item())
        print(f"{r.names[cls]}: {conf:.2f} at {xyxy}")

    # segmentation masks (for -seg models)
    if r.masks is not None:
        for mask in r.masks.data:
            print(f"mask shape: {mask.shape}")

    # keypoints (for -pose models)
    if r.keypoints is not None:
        for kps in r.keypoints.data:
            print(f"pose: {kps.shape}")

Training — full workflow

from ultralytics import YOLO

# detection
model = YOLO("yolo11n.pt")
model.train(
    data="dataset.yaml",
    epochs=100,
    imgsz=640,
    batch=16,
    device="0",
    patience=20,
    save=True,
    plots=True,
)

# validate the best checkpoint
best = YOLO("runs/detect/train/weights/best.pt")
metrics = best.val(data="dataset.yaml", imgsz=640)
print(f"mAP50: {metrics.box.map50:.3f}")

Export — production deployment

model = YOLO("best.pt")

# all supported formats
model.export(format="onnx", imgsz=640, dynamic=True)      # cross-platform
model.export(format="engine", half=True, device="0")        # NVIDIA TensorRT
model.export(format="coreml", imgsz=640)                    # Apple
model.export(format="tflite", imgsz=640)                    # Edge/mobile
model.export(format="torchscript")                           # PyTorch
model.export(format="edgetpu")                               # Google Coral
model.export(format="ncnn")                                  # Mobile (NCNN)
model.export(format="paddle")                                # PaddlePaddle

Tracking (object tracking across frames)

from ultralytics import YOLO

model = YOLO("yolo11n.pt")
results = model.track("video.mp4", persist=True, conf=0.5, stream=True)

for r in results:
    if r.boxes.id is not None:
        ids = r.boxes.id.int().tolist()
        xyxy = r.boxes.xyxy.tolist()
        classes = r.boxes.cls.int().tolist()
        for track_id, box, cls in zip(ids, xyxy, classes):
            print(f"Track {track_id}: {r.names[cls]} at {box}")

Benchmark speed

from ultralytics import YOLO

model = YOLO("yolo11n.pt")
model.benchmark(imgsz=640, device="0")    # prints FPS and ms

Practical Examples

Example 1 — Batch detection on a folder

from ultralytics import YOLO
import glob, json

model = YOLO("yolo11n.pt")
all_results = []

for path in glob.glob("images/*.jpg"):
    results = model(path, conf=0.5, verbose=False)
    for r in results:
        detections = []
        for box in r.boxes:
            detections.append({
                "class": r.names[int(box.cls)],
                "confidence": round(box.conf[0].item(), 3),
                "bbox": [round(v, 1) for v in box.xyxy[0].tolist()],
            })
        all_results.append({"file": path, "detections": detections})

with open("results.json", "w") as f:
    json.dump(all_results, f, indent=2)

Example 2 — Segment objects and save masks

from ultralytics import YOLO

model = YOLO("yolo11n-seg.pt")
results = model("photo.jpg", conf=0.5, save=True, save_txt=True)

for r in results:
    if r.masks is not None:
        print(f"Found {len(r.masks)} segmented objects")
        for i, mask in enumerate(r.masks.data):
            print(f"  Object {i}: mask shape {mask.shape}")

Example 3 — Fine-tune segmentation on custom data

from ultralytics import YOLO

model = YOLO("yolo11n-seg.pt")
model.train(
    data="segment_dataset.yaml",
    epochs=50,
    imgsz=640,
    batch=8,
    device="0",
    patience=15,
)

Dataset YAML for segmentation:

path: /path/to/dataset
train: images/train
val: images/val
names:
  0: defect
  1: scratch

Labels use polygons: class x1 y1 x2 y2 x3 y3 ... (normalized).

Common Patterns

Pattern: production inference with confidence filtering

from ultralytics import YOLO

model = YOLO("best.pt")

def detect(image_path, min_conf=0.5, target_classes=None):
    results = model(image_path, conf=min_conf, verbose=False)
    detections = []
    for r in results:
        for box in r.boxes:
            cls = int(box.cls[0].item())
            if target_classes and cls not in target_classes:
                continue
            detections.append({
                "class": r.names[cls],
                "confidence": round(box.conf[0].item(), 3),
                "bbox": [round(v, 1) for v in box.xyxy[0].tolist()],
            })
    return detections

Pattern: YOLOv8 → YOLO11 migration

# YOLO11 is a drop-in replacement
model = YOLO("yolo11n.pt")    # was: yolov8n.pt
# same API, same arguments
results = model("image.jpg")

Pattern: real-time webcam with OpenCV

import cv2
from ultralytics import YOLO

model = YOLO("yolo11n.pt")
cap = cv2.VideoCapture(0)

while cap.isOpened():
    ret, frame = cap.read()
    if not ret:
        break
    results = model(frame, conf=0.5, verbose=False)
    annotated = results[0].plot()    # draw boxes on frame
    cv2.imshow("YOLO", annotated)
    if cv2.waitKey(1) & 0xFF == ord("q"):
        break
cap.release()
cv2.destroyAllWindows()

Best Practices

• Use YOLO11 (latest) by default; YOLOv8 is still supported and widely documented.
• stream=True for video — avoids loading entire video into memory.
• persist=True with tracking — keeps Re-ID consistent across frames.
• verbose=False during batch inference to suppress per-image logs.
• Export to ONNX for cross-platform; TensorRT for NVIDIA GPU speed.
• model.benchmark() for quick speed comparisons across model sizes.
• Use conf=0.5 as starting threshold; tune for your precision/recall needs.
• For custom training: always start from pretrained weights (yolo11n.pt).

Common Mistakes

Mistake	Fix
Using yolov8 prefix when YOLO11 is available	Use yolo11*.pt — same API, better performance
Forgetting stream=True on video	Loads entire video into memory — use streaming
Wrong label format for segmentation	Seg labels use polygons, not boxes: class x1 y1 x2 y2 ...
Training from scratch with <1000 images	Start from pretrained; fine-tune with more data
show=True in headless environments	Use save=True instead
Export fails — missing dependencies	Install format-specific deps: pip install onnx tensorrt coremltools
CUDA out of memory during training	Lower batch size; use device="cpu" for small experiments

Troubleshooting

Symptom	Cause / Fix
ModuleNotFoundError: No module named 'ultralytics'	pip install ultralytics
No detections on clear images	Lower conf threshold; check imgsz
Training mAP stuck at 0	Wrong label format; check dataset paths in YAML
Export fails for a specific format	Install required packages; check Ultralytics export docs
YOLO11 not recognized	Update ultralytics: pip install -U ultralytics
Tracking IDs reset between frames	Ensure persist=True is set

Related Cheat Sheets

• yolo — YOLO detection concepts and training
• opencv — drawing, video capture, image processing
• pillow — image I/O
• torchvision — torchvision transforms and models
• FastAPI — serving models in an API
• Docker — containerizing for deployment
• GitHub Actions — CI/CD for model pipelines
• PyTorch / Deep Learning — understanding the training loop

Official Documentation

• Ultralytics docs — https://docs.ultralytics.com/
• Ultralytics Python API — https://docs.ultralytics.com/usage/python/
• YOLO11 — https://docs.ultralytics.com/models/yolo11/
• Export formats — https://docs.ultralytics.com/modes/export/

Last Updated

2026-09-06 — Initial version.