YOLOv5 User Guide

1. Quick Start

YOLOv5 is a family of compound-scaled object detection models built on PyTorch, supporting object detection, instance segmentation, and image classification. It provides pre-trained weights, a flexible training pipeline, and export to 11+ deployment formats including ONNX, TensorRT, CoreML, and TensorFlow.

Key features:

• Real-time object detection with five model sizes (nano through extra-large)
• Instance segmentation with pixel-level masks
• Image classification with transfer learning support
• Multi-backend inference (PyTorch, ONNX, TensorRT, OpenVINO, CoreML, TFLite, and more)
• PyTorch Hub integration for two-line inference
• Multi-GPU distributed training (DDP)
• Hyperparameter evolution for automated tuning
• Experiment tracking via ClearML, Comet, W&B, and TensorBoard

Prerequisites: Python 3.8+, PyTorch 1.8+

Quickest path to a detection:

git clone https://github.com/ultralytics/yolov5
cd yolov5
pip install -r requirements.txt
python detect.py --weights yolov5s.pt --source data/images/bus.jpg

image 1/1 data/images/bus.jpg: 640x480 4 persons, 1 bus, 12.3ms
Speed: 1.2ms pre-process, 12.3ms inference, 1.5ms NMS per image at shape (1, 3, 640, 640)
Results saved to runs/detect/exp

Tip

For the fastest setup, use PyTorch Hub — no cloning required. See the PyTorch Hub section below.

What to try next:

• Train a custom model: see Core Usage — Training
• Run segmentation: see Instance Segmentation
• Export for deployment: see Model Export
• See the Admin Guide for full configuration reference and deployment options

2. Installation

System Requirements

Install Methods

pip (recommended)

git clone https://github.com/ultralytics/yolov5
cd yolov5
pip install -r requirements.txt

Docker (GPU)

docker pull ultralytics/yolov5:latest
docker run --ipc=host --gpus all ultralytics/yolov5:latest

Docker (CPU)

docker build -t yolov5-cpu -f utils/docker/Dockerfile-cpu .
docker run --ipc=host yolov5-cpu

Docker (ARM64)

docker build -t yolov5-arm64 -f utils/docker/Dockerfile-arm64 .
docker run --ipc=host yolov5-arm64

Important

Install PyTorch separately first if you need a specific CUDA version. Visit https://pytorch.org/get-started/locally/ for platform-specific install commands. The requirements.txt lists torch>=1.8.0 but does not pin a CUDA variant.

Core Dependencies

Optional Dependencies (by use case)

Post-Install Verification

python detect.py --weights yolov5s.pt --source data/images/bus.jpg

image 1/1 data/images/bus.jpg: 640x480 4 persons, 1 bus, 12.3ms
Results saved to runs/detect/exp

If the command downloads yolov5s.pt automatically, loads the model, runs inference, and saves annotated images to runs/detect/exp, your installation is working.

Warning

On Windows, opencv-python may conflict with opencv-python-headless. If you get import errors, uninstall both and reinstall only one: pip install opencv-python-headless.

Install Troubleshooting

Q: ModuleNotFoundError: No module named 'ultralytics'

The ultralytics package is a required dependency. Install it:

pip install ultralytics>=8.2.64

Q: CUDA out of memory during inference

Reduce image size or use a smaller model:

python detect.py --weights yolov5n.pt --imgsz 320

Q: Model download fails or hangs

Ensure network access and that GitHub releases are reachable. Pre-download weights manually:

python -c "from utils.downloads import attempt_download; attempt_download('yolov5s.pt')"

Q: Slow inference on CPU

Use --half for FP16 (GPU only) or export to ONNX/OpenVINO for optimized CPU inference:

python export.py --weights yolov5s.pt --include onnx openvino

Q: ImportError related to torch

Verify your PyTorch installation:

python -c "import torch; print(torch.__version__); print(torch.cuda.is_available())"

3. Configuration

Model Selection

YOLOv5 provides five model sizes trading speed for accuracy:

Extended P6 models (1280px input, extra detection layer for large objects): yolov5n6, yolov5s6, yolov5m6, yolov5l6, yolov5x6.

Segmentation models use the -seg suffix: yolov5s-seg.pt, yolov5m-seg.pt, etc.

Classification models use the -cls suffix: yolov5s-cls.pt, yolov5m-cls.pt, etc.

Dataset Configuration (YAML)

YOLOv5 uses YAML files to define datasets. Example from data/coco128.yaml:

path: ../datasets/coco128  # dataset root dir
train: images/train2017     # train images (relative to 'path')
val: images/train2017       # val images
test:                       # test images (optional)

# Classes
names:
  0: person
  1: bicycle
  2: car
  # ... 80 classes total

Note

Datasets are expected in ../datasets/ relative to the YOLOv5 root directory. Set the YOLOv5_DATASETS_DIR environment variable to override this default location.

Bundled Dataset Configs

Environment Variables

For the full configuration reference (hyperparameters, model architecture YAML, all environment variables), see the Admin Guide.

4. Core Usage

Object Detection — detect.py

Run inference on images, videos, directories, webcams, streams, or URLs:

# Image
python detect.py --weights yolov5s.pt --source image.jpg

# Video
python detect.py --weights yolov5s.pt --source video.mp4

# Webcam
python detect.py --weights yolov5s.pt --source 0

# Directory
python detect.py --weights yolov5s.pt --source path/to/images/

# Screenshot
python detect.py --weights yolov5s.pt --source screen

# URL / stream
python detect.py --weights yolov5s.pt --source 'https://youtu.be/LNwODJXcvt4'
python detect.py --weights yolov5s.pt --source 'rtsp://example.com/media.mp4'

# Glob pattern
python detect.py --weights yolov5s.pt --source 'path/*.jpg'

Tip

Use --nosave to skip saving output images (useful for benchmarking). Use --view-img to display results live in a window.

Detection CLI Reference

Multi-Format Inference

YOLOv5's DetectMultiBackend transparently loads models in any exported format — pass the exported file to --weights:

python detect.py --weights yolov5s.pt                 # PyTorch
python detect.py --weights yolov5s.torchscript         # TorchScript
python detect.py --weights yolov5s.onnx               # ONNX
python detect.py --weights yolov5s_openvino_model      # OpenVINO
python detect.py --weights yolov5s.engine              # TensorRT
python detect.py --weights yolov5s.mlpackage           # CoreML (macOS)
python detect.py --weights yolov5s_saved_model         # TF SavedModel
python detect.py --weights yolov5s.pb                  # TF GraphDef
python detect.py --weights yolov5s.tflite              # TF Lite
python detect.py --weights yolov5s_paddle_model        # PaddlePaddle

Training — train.py

Train a detection model from pretrained weights or from scratch:

# Fine-tune YOLOv5s on COCO128 dataset
python train.py --weights yolov5s.pt --data coco128.yaml --epochs 100 --batch-size 16 --imgsz 640

train: weights=yolov5s.pt, cfg=, data=coco128.yaml, hyp=data/hyps/hyp.scratch-low.yaml, epochs=100, batch_size=16
                 Class     Images  Instances          P          R      mAP50   mAP50-95
                   all        128        929      0.732      0.681      0.724      0.468

Important

Set --batch-size -1 to enable autobatch, which automatically determines the largest batch size that fits in GPU memory.

Training CLI Reference

Multi-GPU Training (DDP)

python -m torch.distributed.run --nproc_per_node 4 train.py \
  --weights yolov5s.pt --data coco.yaml --epochs 100 --batch-size 64 --device 0,1,2,3

Warning

When using DDP, the --batch-size is the total across all GPUs (divided evenly). With 4 GPUs and --batch-size 64, each GPU processes 16 images per batch. The --workers value is per rank.

Validation — val.py

Evaluate model performance on a validation or test split:

python val.py --weights yolov5s.pt --data coco128.yaml --imgsz 640

                 Class     Images  Instances          P          R      mAP50   mAP50-95
                   all        128        929      0.732      0.681      0.724      0.468
Speed: 0.5ms pre-process, 4.8ms inference, 1.2ms NMS per image at shape (32, 3, 640, 640)

Validation CLI Reference

Model Export — export.py

Export trained models to deployment formats:

python export.py --weights yolov5s.pt --include torchscript onnx openvino engine

export: weights=yolov5s.pt, include=['torchscript', 'onnx', 'openvino', 'engine']
YOLOv5s summary: 213 layers, 7225885 parameters
PyTorch: starting export...
TorchScript: starting export with torch X.X.X...
ONNX: starting export with onnx X.X.X...

Supported Export Formats

Note

Edge TPU and TF.js exports are supported for export but not for YOLOv5's built-in inference pipeline. These formats are intended for use in their respective runtime environments.

Export CLI Reference

Instance Segmentation

YOLOv5 supports instance segmentation via dedicated scripts in the segment/ directory:

# Predict with segmentation model
python segment/predict.py --weights yolov5s-seg.pt --source data/images/bus.jpg

# Train segmentation model
python segment/train.py --weights yolov5s-seg.pt --data coco128-seg.yaml --epochs 100

# Validate segmentation model
python segment/val.py --weights yolov5s-seg.pt --data coco128-seg.yaml

Segmentation-specific flags (in addition to the standard detection flags):

Tip

Use --retina-masks for higher-quality mask visualization at the cost of slightly slower post-processing.

Image Classification

Train and predict with classification models:

# Train classifier
python classify/train.py --model yolov5s-cls.pt --data imagenette160 --epochs 10 --imgsz 224

# Predict
python classify/predict.py --weights yolov5s-cls.pt --source image.jpg

# Validate
python classify/val.py --weights yolov5s-cls.pt --data imagenette160

Classification supports torchvision pretrained models as starting points:

python classify/train.py --model resnet50 --data cifar100 --epochs 10

Note

Classification uses 224x224 image size by default (vs 640x640 for detection/segmentation). The --optimizer default is Adam with lr0=0.001 (vs SGD with lr0=0.01 for detection).

Classification-Specific Flags

PyTorch Hub

Load YOLOv5 models directly without cloning the repository:

import torch

# Load a pretrained model
model = torch.hub.load('ultralytics/yolov5', 'yolov5s', pretrained=True)

# Inference on an image
results = model('https://ultralytics.com/images/zidane.jpg')

# Show results
results.show()
results.print()

# Access detections as pandas DataFrame
df = results.pandas().xyxy[0]
print(df)

   xmin    ymin    xmax    ymax  confidence  class  name
0  749.5   43.5  1148.0   704.0       0.874      0  person
1  114.2  198.7   1148.0  708.9       0.624      0  person

Available Hub models: yolov5n, yolov5s, yolov5m, yolov5l, yolov5x, yolov5n6, yolov5s6, yolov5m6, yolov5l6, yolov5x6.

Load a custom-trained model:

model = torch.hub.load('ultralytics/yolov5', 'custom', path='best.pt')

Benchmarks

Compare model performance across all export formats:

python benchmarks.py --weights yolov5s.pt --imgsz 640

Benchmarks complete (120.5s)
     Format  Size (MB)  mAP50-95  Inference time (ms)
   PyTorch       14.1    0.3720                  8.2
TorchScript       28.1    0.3720                  7.5
       ONNX       28.0    0.3720                  9.1
   OpenVINO       28.2    0.3720                  6.3
   TensorRT       18.5    0.3720                  3.1

5. Common Tasks

Train a Custom Object Detection Model

Goal: Train YOLOv5 on your own labeled dataset.

Prerequisites: Images with YOLO-format labels (class x_center y_center width height, normalized 0-1).

1. Organize your dataset:

   datasets/
   └── my_dataset/
       ├── images/
       │   ├── train/
       │   └── val/
       └── labels/
           ├── train/
           └── val/
   

2. Create a dataset YAML:

   path: ../datasets/my_dataset
   train: images/train
   val: images/val
   
   names:
     0: cat
     1: dog
   

3. Train:

   python train.py --weights yolov5s.pt --data my_dataset.yaml --epochs 100 --imgsz 640
   

4. Verify: Check runs/train/exp/ for training curves, confusion matrix, and best.pt.

If it fails: Ensure label files exist alongside images with matching filenames (.txt extension). Verify label format with no empty lines.

Resume Interrupted Training

# Resume most recent run
python train.py --resume

# Resume a specific run
python train.py --resume runs/train/exp5/weights/last.pt

Train From Scratch (No Pretrained Weights)

python train.py --weights '' --cfg yolov5s.yaml --data coco128.yaml --epochs 300 \
  --hyp data/hyps/hyp.scratch-low.yaml

Freeze Backbone for Transfer Learning

# Freeze the first 10 layers (backbone)
python train.py --weights yolov5s.pt --data my_dataset.yaml --freeze 10

Hyperparameter Evolution

Automatically search for optimal hyperparameters:

python train.py --weights yolov5s.pt --data coco128.yaml --evolve 300

Results are saved to runs/train/evolve/ with hyp_evolve.yaml containing the best configuration.

Run Detection on Video with Custom Thresholds

python detect.py --weights best.pt --source video.mp4 \
  --conf-thres 0.5 --iou-thres 0.3 --max-det 50 \
  --save-txt --save-conf

Filter Detections by Class

# Only detect persons (class 0) and cars (class 2)
python detect.py --weights yolov5s.pt --source image.jpg --classes 0 2

Export and Run with TensorRT

# Export
python export.py --weights yolov5s.pt --include engine --half --device 0

# Run inference with exported engine
python detect.py --weights yolov5s.engine --source image.jpg --device 0

Export with Dynamic Batch Size

python export.py --weights yolov5s.pt --include onnx --dynamic

Serve Model via REST API

python utils/flask_rest_api/restapi.py --port 5000 --model yolov5s

Send an inference request:

curl -X POST -F "image=@image.jpg" http://localhost:5000/v1/object-detection/yolov5s

[{"xmin": 749.5, "ymin": 43.5, "xmax": 1148.0, "ymax": 704.0, "confidence": 0.874, "class": 0, "name": "person"}]

Cache Images for Faster Training

# Cache to RAM (fastest, requires sufficient memory)
python train.py --weights yolov5s.pt --data coco128.yaml --cache ram

# Cache to disk
python train.py --weights yolov5s.pt --data coco128.yaml --cache disk

Use Cosine Learning Rate Scheduler

python train.py --weights yolov5s.pt --data coco128.yaml --cos-lr

Save COCO-JSON Results for Official Evaluation

python val.py --weights yolov5s.pt --data coco.yaml --save-json

Save Detection Results as CSV

python detect.py --weights yolov5s.pt --source images/ --save-csv

6. Troubleshooting

Diagnostic Decision Tree

Problem?
├── Training fails → Check GPU memory, dataset format, YAML path
├── Poor accuracy → Check dataset quality, try larger model, more epochs
├── Slow inference → Try smaller model, --half, export to TensorRT/OpenVINO
├── Export fails → Check optional dependency installed, compatible versions
└── Import error → Check Python/PyTorch versions, reinstall requirements

Error: FileNotFoundError: Source path '...' does not exist

Cause: The --source path does not exist on the filesystem.

Solution:

1. Verify the file or directory path exists
2. Check for typos in the path
3. For URL sources, ensure the URL is accessible

Prevention: Use absolute paths or verify paths before running.

Error: RuntimeError: failed to load ONNX file: ...

Cause: The ONNX file is corrupted or was generated with an incompatible opset version.

Solution:

1. Re-export the model: python export.py --weights yolov5s.pt --include onnx --opset 17
2. Ensure onnx and onnxruntime versions are compatible

Prevention: Always verify exports with python benchmarks.py --weights yolov5s.onnx.

Error: NotImplementedError: ERROR: YOLOv5 TF.js inference is not supported

Cause: TF.js models cannot be used for inference within YOLOv5's Python pipeline.

Solution: Use the exported TF.js model directly in a JavaScript/browser environment. For Python inference, use TF SavedModel or TFLite instead.

Error: CUDA out of memory

Cause: Batch size or image size is too large for GPU memory.

Solution:

1. Reduce --batch-size (or use -1 for autobatch)
2. Reduce --imgsz
3. Use a smaller model variant
4. Use --cache ram to reduce dataloader overhead

Prevention: Monitor GPU memory with nvidia-smi. Use autobatch (--batch-size -1).

Error: aten::nonzero not supported on MPS backend

Cause: Apple Silicon MPS backend does not support all PyTorch operations used by YOLOv5. (GitHub issue #8508)

Solution: Fall back to CPU:

python detect.py --weights yolov5s.pt --device cpu

Prevention: Use CUDA GPUs for full feature support. MPS support is partial.

Warning

Apple MPS backend has known compatibility issues with YOLOv5. Use --device cpu if you encounter MPS-related errors.

Error: Cannot run parallel inference with DDP

Cause: DDP is designed for training, not inference. (GitHub issue #9687)

Solution: Use single-GPU inference or batch inference instead of DDP for prediction.

Error: Dataset not found

Cause: The dataset path in the YAML file does not exist. Auto-download may have failed.

Solution:

1. Check the path field in your dataset YAML
2. Ensure ../datasets/ directory exists relative to your YOLOv5 root
3. Set YOLOv5_DATASETS_DIR to a custom location
4. Manually download the dataset

Error: Optimizer ... not implemented

Cause: Invalid optimizer name passed via --optimizer.

Solution: Use one of the supported optimizers: SGD, Adam, or AdamW.

Error: ValueError with ClearML authentication

Cause: ClearML is installed but not configured with valid credentials. (GitHub issue #9877)

Solution: Run clearml-init to configure credentials, or uninstall ClearML if not needed:

pip uninstall clearml

Caution

Training and validation commands auto-detect installed loggers (ClearML, Comet, W&B). If a logger package is installed but not configured, it may cause authentication errors. Either configure the logger or uninstall the package.

Error: NotImplementedError: --task ... not in ("train", "val", "test", "speed", "study")

Cause: Invalid --task value passed to val.py or segment/val.py.

Solution: Use one of the supported task values: train, val, test, speed, or study.

Error: FileNotFoundError: ... does not exist during data loading

Cause: An image or label file referenced in the dataset is missing.

Solution:

1. Verify all images exist at the paths listed in your dataset
2. Run label verification: check for corresponding .txt files in labels directory
3. Re-download the dataset if using a built-in config

Prevention: Use --cache to validate all images before training starts.

7. FAQ

Q: What image formats does YOLOv5 support for inference?

Images: bmp, dng, jpeg, jpg, mpo, png, tif, tiff, webp, pfm. Videos: asf, avi, gif, m4v, mkv, mov, mp4, mpeg, mpg, ts, wmv, webm.

Q: How do I use multiple GPUs for training?

Use DDP with torch.distributed.run:

python -m torch.distributed.run --nproc_per_node 4 train.py --device 0,1,2,3 --batch-size 64

For inference, specify a single device: --device 0.

Q: Can I train on a CPU?

Yes, pass --device cpu. Training will be significantly slower than GPU. This is mainly useful for testing or very small datasets.

Q: How do I use custom pretrained weights?

Pass the path to your .pt file via --weights:

python train.py --weights path/to/my_model.pt --data my_data.yaml

Q: What is the difference between --conf-thres in detect.py vs val.py?

detect.py uses 0.25 default (higher, for clean visual output). val.py uses 0.001 default (very low, to compute full precision-recall curves for mAP evaluation).

Q: How do I convert my model to ONNX for deployment?

python export.py --weights best.pt --include onnx --simplify

Q: What is rectangular training (--rect)?

Rectangular training pads images to the minimum size rather than square, reducing wasted computation on non-square images. It can improve training speed but may slightly affect accuracy.

Q: How does EarlyStopping work?

Training stops if fitness (mAP@0.5 + mAP@0.5:0.95) does not improve for --patience consecutive epochs (default: 100). The best weights are always saved to best.pt regardless.

Q: Can I use YOLOv5 for real-time video detection?

Yes. Use a webcam source and a fast model:

python detect.py --weights yolov5n.pt --source 0 --view-img

Q: What are the P6 models (e.g., yolov5s6)?

P6 models add an extra detection layer (P6) for large objects. They use 1280px input by default and are better suited for high-resolution images with objects at various scales.

Q: How do I access detection results programmatically?

Use --save-txt for label files, --save-csv for CSV, or --save-json (val.py) for COCO-JSON format. For Python programmatic access, use PyTorch Hub:

results = model(img)
df = results.pandas().xyxy[0]  # DataFrame: xmin, ymin, xmax, ymax, confidence, class, name

Q: What hyperparameter files are included?

Q: How do I check model FLOPs and parameters?

python models/yolo.py --cfg yolov5s.yaml

Or use thop during training — FLOPs are logged automatically.

Q: Can I ensemble multiple models?

Yes, pass multiple weights to val.py:

python val.py --weights yolov5s.pt yolov5m.pt --data coco.yaml

The attempt_load() function in models/experimental.py creates an Ensemble that averages predictions.

Q: What is --vid-stride?

It controls how many video frames to skip between processed frames. --vid-stride 2 processes every other frame, doubling effective throughput at the cost of temporal resolution.