{"id":1767,"library":"ultralytics","title":"Ultralytics YOLO","description":"Ultralytics YOLO is a cutting-edge deep learning library for state-of-the-art computer vision tasks including object detection, instance segmentation, pose estimation, and image classification, built around the YOLO architecture. It maintains a rapid release cadence, frequently delivering stability improvements and new features, with the current stable version being 8.4.36.","status":"active","version":"8.4.36","language":"en","source_language":"en","source_url":"https://github.com/ultralytics/ultralytics","tags":["computer-vision","yolo","object-detection","segmentation","pose-estimation","classification","deep-learning","pytorch"],"install":[{"cmd":"pip install ultralytics","lang":"bash","label":"Stable release"},{"cmd":"pip install ultralytics[all]","lang":"bash","label":"With all dependencies (e.g., for segmentation, tracking)"}],"dependencies":[{"reason":"Core deep learning framework.","package":"torch","optional":false},{"reason":"Computer vision utilities for PyTorch.","package":"torchvision","optional":false},{"reason":"Image processing for data loading and visualization.","package":"opencv-python","optional":false}],"imports":[{"note":"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).","wrong":"from ultralytics.yolo.v8.detect import DetectionPredictor","symbol":"YOLO","correct":"from ultralytics import YOLO"}],"quickstart":{"code":"from ultralytics import YOLO\nimport os\n\n# Load a pretrained YOLOv8n model\nmodel = YOLO('yolov8n.pt')\n\n# Use the model for training (example with dummy data for brevity)\n# For a real run, ensure 'coco128.yaml' or your custom data path is valid\n# You might need to download a dataset like coco128 first.\n# For a quick local test, you can uncomment and try to train on a tiny dataset:\n# try:\n#     results = model.train(data='coco128.yaml', epochs=1, imgsz=640)\n# except Exception as e:\n#     print(f\"Training failed (might be missing dataset or GPU): {e}\")\n\n# Use the model for prediction on an image\nimage_path = 'https://ultralytics.com/images/bus.jpg'\nresults = model(image_path)\n\n# Process results\nfor r in results:\n    print(f\"Detected {len(r.boxes)} objects.\")\n    # r.show()  # Uncomment to display the image with detections\n\n# Export the model to ONNX format\nmodel.export(format='onnx')","lang":"python","description":"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."},"warnings":[{"fix":"Refactor code to use the `from ultralytics import YOLO` and the `model = YOLO('model.pt')` interface for all tasks (train, predict, export, val).","message":"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.","severity":"breaking","affected_versions":"<8.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All v8.x, particularly prior to v8.4.36"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All v8.x, particularly prior to v8.4.35"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}