YOLOv5 Object Detector (Pip Package)

Common errors

• ModuleNotFoundError: No module named 'yolov5.utils.general'

  cause This error often occurs due to issues with package installation, corrupted environment, or internal pathing conflicts, particularly in older versions.
  fix First, 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'

  cause Your `huggingface_hub` library version is too new and introduces breaking changes that conflict with the `yolov5` package's expected API.
  fix Downgrade `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'

  cause 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.
  fix Use 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.

  cause PyTorch is unable to detect a CUDA-enabled GPU, or CUDA drivers/toolkit are not correctly installed or configured for your PyTorch installation.
  fix Ensure 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())`.

Warnings

• breaking Version 7.0.14 introduced an upper limit for `huggingface_hub` (<0.16.0) to prevent import errors caused by recent changes in the library.
  Fix: Ensure 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.
• gotcha This `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.).
  Fix: Always 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.
• gotcha Occasional `ModuleNotFoundError` errors for internal modules like `yolov5.utils.general` have been reported, often related to packaging or environment issues.
  Fix: Ensure 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.
• gotcha Roboflow 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.
  Fix: Install `roboflow` as an optional dependency and provide the `--roboflow_token` argument when using CLI commands for Roboflow datasets.

Install

• pip install yolov5 Stable Release
• pip install yolov5[all] # Includes all optional dependencies for full functionality Full Installation

Imports

• YOLOv5
  wrong:

  import yolov5

  correct:

  from yolov5 import YOLOv5

  The primary interface is a class, not direct functions on the module.

Quickstart

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")