Install & Compatibility
Where this runs
tested against v8.4.131 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.10
✕ build_error
✓ 89.05s
py 3.11
✕ build_error
✓ 84.05s
py 3.12
✕ build_error
✓ 74.7s
py 3.13
✕ build_error
✓ 71.95s
py 3.9
✕ build_error
✕ timeout
5350MB installed
● package 5350MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
YOLO
✓ from ultralytics import YOLO
✗ from ultralytics.yolo.v8.detect import DetectionPredictor
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).
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')
yolo --version
Debug
Known issues
breakingThe 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.fixRefactor code to use the `from ultralytics import YOLO` and the `model = YOLO('model.pt')` interface for all tasks (train, predict, export, val). affects: <8.0.0
gotchaTraining 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.fixAlways 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.
affects: All v8.x, particularly prior to v8.4.36
gotchaOptimal 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.fixVerify `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.
affects: All versions
gotchaData 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.fixCarefully 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.
affects: All versions
gotchaTraining 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.fixIf '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.
affects: All v8.x, particularly prior to v8.4.35
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'ultralytics.yolo'
Older tutorials or code snippets using the deprecated direct import path `ultralytics.yolo` are incompatible with the current simplified API, where core functionalities are exposed differently.
fixUse the updated import statement to access the `YOLO` class directly: `from ultralytics import YOLO`.
ERROR: Could not find a version that satisfies the requirement torch>=1.8.0 (from ultralytics)
Pip is unable to find a compatible PyTorch package, often due to specific CUDA requirements for your system (GPU vs. CPU), a Python version mismatch, or an outdated pip cache, preventing `ultralytics` from installing its dependencies.
fixInstall PyTorch manually first, following the official PyTorch website's instructions for your specific setup (e.g., CUDA version), then install `ultralytics`. Example for CUDA 11.8: `pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118` followed by `pip install ultralytics`.
AttributeError: 'list' object has no attribute 'boxes'
The `model.predict()` method returns a list of `Results` objects (one for each input image), and you are attempting to access attributes like `boxes` directly on the list itself instead of iterating through the individual `Results` objects or accessing a specific one.
fixIterate through the list of `Results` objects or select a specific one to access its attributes. Example: `results = model.predict(source='image.jpg'); for r in results: print(r.boxes)` or `first_image_results = results[0]; print(first_image_results.boxes)`.
ImportError: cannot import name 'YOLO' from 'ultralytics' (unknown location)
This error typically occurs if your installed `ultralytics` package is an older version that doesn't expose the `YOLO` class directly at the top level, or if there's a local file named `ultralytics.py` shadowing the package.
fixUpgrade `ultralytics` to the latest version using `pip install --upgrade ultralytics` and ensure no local file or directory shadows the `ultralytics` package name.
FileNotFoundError: [Errno 2] No such file or directory: 'yolov8n.pt'
The specified model weights file (e.g., `yolov8n.pt`), input image, or data configuration YAML file does not exist at the provided path or is inaccessible from the current working directory.
fixVerify the file path is correct, ensure the file actually exists, and check your current working directory. If using pre-trained models like `yolov8n.pt`, they are typically downloaded automatically; ensure you have an active internet connection or provide a local path if already downloaded.
Upgrade
Version history
8.4.131latest on PyPI · released Aug 27, 2026
Audit
Dependencies
torchrequiredCore deep learning framework.
torchvisionrequiredComputer vision utilities for PyTorch.
opencv-pythonrequiredImage processing for data loading and visualization.