Install & Compatibility
Where this runs
tested against v7.0.14 · 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
✕ dependency_conflict
✓ 107.45s
py 3.11
✕ dependency_conflict
✓ 99.48s
py 3.12
✕ dependency_conflict
✓ 93.28s
py 3.13
✕ no_wheel
✓ 87.13s
py 3.9
✕ dependency_conflict
✕ timeout
5811MB installed
● package 5811MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
YOLOv5
✓ from yolov5 import YOLOv5
✗ import yolov5
The primary interface is a class, not direct functions on the module.
This quickstart demonstrates how to load a pretrained YOLOv5 model, set inference parameters, and perform object detection on an image. The `YOLOv5` class manages model loading and inference, providing easy access to prediction results.
from yolov5 import YOLOv5
import os
# Load a pretrained YOLOv5 model
# Options: yolov5s, yolov5m, yolov5l, yolov5x
model = YOLOv5(model_path="yolov5s.pt", device="cpu") # Use device="cuda:0" for GPU
# Set model parameters
model.conf = 0.25 # NMS confidence threshold
model.iou = 0.45 # NMS IoU threshold
model.max_det = 1000 # Maximum number of detections per image
# Perform inference on an image (e.g., from a URL or local path)
# Example image from COCO dataset
img_path = "https://ultralytics.com/images/zidane.jpg"
results = model(img_path, size=640)
# Process and display results
predictions = results.pred[0]
boxes = predictions[:, :4]
scores = predictions[:, 4]
categories = predictions[:, 5]
print(f"Detected {len(boxes)} objects:")
for i in range(len(boxes)):
print(f" Box: {boxes[i].tolist()}, Score: {scores[i]:.2f}, Category: {int(categories[i])}")
# Optional: Save results to a directory
# results.save(save_dir="./results")
Debug
Known issues
breakingVersion 7.0.14 introduced an upper limit for `huggingface_hub` (<0.16.0) to prevent import errors caused by recent changes in the library.fixEnsure your `huggingface_hub` package is within the compatible range (e.g., `pip install huggingface-hub<0.16`). If you experience `ImportError` related to `log_metrics_to_hubble`, this is likely the cause.
affects: 7.0.14 onwards (fix for previous versions)
gotchaThis `yolov5` pip package is a wrapper around the original Ultralytics YOLOv5 repository. While it provides the same models, its programmatic API (`from yolov5 import YOLOv5`) differs from directly cloning and running the Ultralytics repository scripts or using the newer `ultralytics` pip package (YOLOv8, YOLOv5, etc.).fixAlways refer to the `fcakyon/yolov5-pip` GitHub README for the correct programmatic usage, particularly the `YOLOv5` class interface. Do not mix with direct script calls from the original Ultralytics repo or the `ultralytics` package for YOLOv8.
affects: All versions
gotchaOccasional `ModuleNotFoundError` errors for internal modules like `yolov5.utils.general` have been reported, often related to packaging or environment issues.fixEnsure a clean installation in a dedicated virtual environment (`python -m venv .venv && source .venv/bin/activate && pip install yolov5`). Update to the latest version (`pip install --upgrade yolov5`) as these issues are often patched.
affects: Prior to 7.0.13, intermittent in some environments.
gotchaRoboflow integration requires the `roboflow` package to be installed (e.g., `pip install yolov5[roboflow]` or `pip install roboflow>=0.2.27`) and typically a Roboflow API token.fixInstall `roboflow` as an optional dependency and provide the `--roboflow_token` argument when using CLI commands for Roboflow datasets.
affects: All versions with Roboflow integration (7.0.8+)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'yolov5.utils.general'
This error often occurs due to issues with package installation, corrupted environment, or internal pathing conflicts, particularly in older versions.
fixFirst, try updating the package (`pip install --upgrade yolov5`). If the problem persists, try a clean reinstallation in a fresh virtual environment. This specific issue was addressed in version 7.0.13.
ImportError: cannot import name 'log_metrics_to_hubble' from 'huggingface_hub'
Your `huggingface_hub` library version is too new and introduces breaking changes that conflict with the `yolov5` package's expected API.
fixDowngrade `huggingface_hub` to a compatible version. For `yolov5` 7.0.14+, this typically means `pip install huggingface-hub<0.16.0`. Check the `yolov5` release notes for the exact compatible range.
AttributeError: module 'yolov5' has no attribute 'load'
You are attempting to use the `load()` function, which is a common pattern in the original Ultralytics YOLOv5 repository scripts or some other machine learning libraries, but not directly exposed by the `fcakyon/yolov5-pip` package's top-level module.
fixUse the class-based API: `from yolov5 import YOLOv5` and then instantiate the model with `model = YOLOv5(model_path='yolov5s.pt', device='cpu')`.
torch.cuda.is_available() returned False, but cuda is selected. Check your CUDA installation.
PyTorch is unable to detect a CUDA-enabled GPU, or CUDA drivers/toolkit are not correctly installed or configured for your PyTorch installation.
fixEnsure you have CUDA drivers and the appropriate CUDA Toolkit installed for your system. Reinstall PyTorch with CUDA support, matching your CUDA Toolkit version (e.g., `pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118`). Verify with `import torch; print(torch.cuda.is_available())`.
Upgrade
Version history
7.0.14latest on PyPI · released Nov 11, 2024
Audit
Dependencies
huggingface_hubrequiredUsed for model download and integration; specific versions can cause import errors.
neptuneoptionalFor experiment tracking integration.
roboflowoptionalFor direct integration with Roboflow datasets and services.