yolov3 README

The project's README from github.com/ultralytics/yolov3. As one markdown file: README.md.

Ultralytics YOLOv3 banner

中文 | 한국어 | 日本語 | Русский | Deutsch | Français | Español | Português | Türkçe | Tiếng Việt | العربية

YOLOv3 CI Docker Pulls Discord Ultralytics Forums Ultralytics Reddit
Open In Colab

Ultralytics YOLOv3 is a PyTorch implementation of the YOLOv3 (You Only Look Once, version 3) real-time object detection model. YOLOv3 frames detection as a single regression problem, predicting bounding boxes and class probabilities directly from full images in one forward pass — making it fast, accurate, and straightforward to train and deploy.

This repository packages the three classic YOLOv3 detection models — YOLOv3, YOLOv3-SPP, and YOLOv3-tiny — with training, validation, inference, and export tooling, and reuses shared utilities from the ultralytics package.

Find detailed guidance in the Ultralytics YOLOv3 Docs. Get support via GitHub Issues, and join the conversation on Discord, Reddit, and the Ultralytics Forums.

For commercial use, request an Enterprise License at Ultralytics Licensing.

Ultralytics GitHub space Ultralytics LinkedIn space Ultralytics Twitter space Ultralytics YouTube space Ultralytics TikTok space Ultralytics BiliBili space Ultralytics Discord

📚 Documentation

See the Ultralytics YOLOv3 Docs for full documentation. The quickstart examples below cover installation, inference, and training with this repository.

Install

Clone the repository and install the dependencies from requirements.txt in a Python>=3.8.0 environment with PyTorch>=1.8.

# Clone the YOLOv3 repository
git clone https://github.com/ultralytics/yolov3

# Navigate to the cloned directory
cd yolov3

# Install required packages
pip install -r requirements.txt
Inference with PyTorch Hub

Load YOLOv3 directly through PyTorch Hub. Weights download automatically on first use.

import torch

# Load a YOLOv3 model (choices: 'yolov3', 'yolov3_spp', 'yolov3_tiny')
model = torch.hub.load("ultralytics/yolov3", "yolov3", pretrained=True)

# Run inference on an image (local file, URL, PIL image, OpenCV frame, or numpy array)
results = model("https://ultralytics.com/images/zidane.jpg")

# Inspect the results
results.print()  # print detections to the console
results.show()  # display the annotated image
results.save()  # save the annotated image to runs/detect/exp
Inference with detect.py

detect.py runs inference on a wide range of sources, downloading models automatically and saving results to runs/detect.

python detect.py --weights yolov3.pt --source 0                              # webcam
python detect.py --weights yolov3.pt --source img.jpg                        # image
python detect.py --weights yolov3.pt --source vid.mp4                        # video
python detect.py --weights yolov3.pt --source screen                         # screenshot
python detect.py --weights yolov3.pt --source path/                          # directory
python detect.py --weights yolov3.pt --source 'path/*.jpg'                   # glob
python detect.py --weights yolov3.pt --source 'rtsp://example.com/media.mp4' # RTSP, RTMP, HTTP stream
Training

Train YOLOv3 on the COCO dataset. Models and datasets download automatically. Use the largest --batch-size your hardware allows.

# Train YOLOv3-tiny
python train.py --data coco.yaml --epochs 300 --weights '' --cfg yolov3-tiny.yaml --batch-size 64

# Train YOLOv3
python train.py --data coco.yaml --epochs 300 --weights '' --cfg yolov3.yaml --batch-size 32

# Train YOLOv3-SPP
python train.py --data coco.yaml --epochs 300 --weights '' --cfg yolov3-spp.yaml --batch-size 16

Validate accuracy with python val.py --weights yolov3.pt --data coco.yaml, and export to other formats (TorchScript, ONNX, OpenVINO, TensorRT, CoreML, and PaddlePaddle) with python export.py --weights yolov3.pt --include onnx.

Tutorials

These guides cover the shared Ultralytics training framework and apply to YOLOv3:

🧠 Architecture

YOLOv3 builds detection on a few core ideas that make it both accurate and fast:

The repository ships three variants of this architecture:

Models are defined declaratively in models/*.yaml and built by parse_model() in models/yolo.py, so the architecture can be inspected and modified without writing Python.

🏋️ Pretrained Checkpoints

All three models are trained on COCO (80 classes) and download automatically from the YOLOv3 release assets on first use.

Model Description
yolov3-tiny.pt Lightweight two-scale model — the fastest option, ideal for CPU and edge devices.
yolov3.pt The original Darknet-53 model — a strong balance of speed and accuracy.
yolov3-spp.pt Adds Spatial Pyramid Pooling for a larger receptive field and improved accuracy.

🧩 Integrations

Ultralytics integrates with leading AI platforms to extend dataset labeling, training, visualization, and model management. Explore how partners such as Weights & Biases, Comet ML, Roboflow, and Intel OpenVINO can streamline your workflow at Ultralytics Integrations.

Ultralytics active learning integrations

🤔 Why YOLOv3?

YOLOv3 was a landmark in real-time object detection and remains a dependable, well-understood baseline:

For the broader family of Ultralytics YOLO models, see the Ultralytics repository.

☁️ Environments

Get started quickly with pre-configured environments. Click an icon below for setup details.

Run on Gradient Open In Colab Open In Kaggle Docker Image AWS Marketplace GCP Quickstart

🤝 Contribute

Contributions are welcome! Please see the Contributing Guide to get started, and share your feedback through the Ultralytics Survey. Thank you to all our contributors!

Ultralytics open-source contributors

📜 License

Ultralytics offers two licensing options:

📧 Contact

For bug reports and feature requests, please use GitHub Issues. For questions and discussion, join our Discord, Reddit, and the Ultralytics Forums.


Ultralytics GitHub space Ultralytics LinkedIn space Ultralytics Twitter space Ultralytics YouTube space Ultralytics TikTok space Ultralytics BiliBili space Ultralytics Discord

yolov3 (ultralytics/yolov3)

Searching Database…

10.6K ·GitHub
Yolov3
What is this?Ultralytics' PyTorch implementation of the YOLOv3 real-time object detector, packaging three model variants - YOLOv3, YOLOv3-SPP and YOLOv3-tiny - with training, validation, inference and multi-format export tooling.
Is this a library I import, or a set of scripts I run?Both. You can load the models in code through PyTorch Hub, or run the bundled scripts from the command line: detect.py for inference, plus train.py, val.py and export.py.
How do I get it running?Clone the repository and install the dependencies from requirements.txt in a Python>=3.8.0 environment with PyTorch>=1.8, then run the scripts or load models via PyTorch Hub.
What do I need installed before I can use it?Python 3.8+ with PyTorch 1.8+ is all you need; the rest comes from requirements.txt, and pretrained weights and datasets download automatically - no API keys or accounts.
Is YOLOv3 still the model I should be using?It ships the classic, well-understood YOLOv3 architecture - a dependable baseline, but for Ultralytics' broader, newer YOLO family you would use the main Ultralytics repository instead.
Will it run on my Windows machine, or is this Linux-only?It is plain Python and PyTorch, so it runs on Linux, macOS and Windows alike.
Does everything run locally on my own hardware?Yes - it is a local Python/PyTorch codebase with no cloud component; you train and run inference on your own machine.
Can I use it in a commercial product?Not under the default license: AGPL-3.0 is aimed at research and collaboration. Commercial use requires a paid Enterprise License from Ultralytics.
What is the difference between YOLOv3, YOLOv3-SPP, and YOLOv3-tiny?YOLOv3 is the full Darknet-53 model, the best balance of speed and accuracy. YOLOv3-SPP adds a Spatial Pyramid Pooling block for a larger receptive field and a small accuracy gain. YOLOv3-tiny is a compact two-scale model, the fastest option, optimized for CPU and edge devices.
What can it detect out of the box?The shipped checkpoints are pretrained on COCO with 80 classes, so it recognizes those objects immediately without any training on your side.
Can I train it on my own dataset?Yes - the Train Custom Data guide walks you through it, and the shared Ultralytics training framework adds multi-GPU training, automatic hyperparameter tuning, test-time augmentation, model ensembling and transfer learning with frozen layers.
Which formats can I export a trained model to for deployment?export.py handles TorchScript, ONNX, OpenVINO, TensorRT, CoreML and PaddlePaddle - for example: python export.py --weights yolov3.pt --include onnx.
What are similar projects?yolov5, YOLOX, High-Angle_Robust_Fast_FaceAlignment, RelateAnything, yolov7, ultralytics, SolarWM, Pytorch-UNet
Which topics is it in?coreml, tensorrt, transfer-learning, convolutional-neural-networks, yolo, cnn, model-training, distributed-training, validation, edge-ai, neural-networks, object-detection
Creator
ultralytics
Size
11.1 MB
Stars
10.6K
Updated
CommitOct 17Releasev9.6.0Nov 14
Age
8y
Commits · 90 Days