CONTRIBUTING

Contributing to Ultralytics YOLOv3 🚀

We love your input! We want to make contributing to Ultralytics YOLOv3 as easy and transparent as possible, whether you're:

- Reporting a bug
- Discussing the current state of the code
- Submitting a fix
- Proposing a new feature
- Becoming a maintainer

Ultralytics YOLO models are successful thanks to the collective efforts of our community. Every improvement you contribute helps advance the possibilities of AI and computer vision! 😃

🚀 Submitting a Pull Request (PR)

We greatly appreciate contributions in the form of pull requests. To make the review process as smooth as possible, please follow these steps:

1. Fork the repository: Fork ultralytics/yolov3 to your GitHub account.
2. Create a branch: Create a branch in your fork with a clear, descriptive name (e.g., fix-issue-123, add-feature-xyz).
3. Make your changes: Keep them minimal and focused on a single bug fix or feature. Ensure your code follows the project's style and doesn't introduce new errors or warnings.
4. Test your changes: There is no pytest suite — the CI workflow smoke-tests the real scripts. Run a fast local equivalent before submitting:

bash

python train.py --imgsz 64 --batch 32 --weights yolov3-tiny.pt --cfg yolov3-tiny.yaml --epochs 1 --device cpu
   python val.py --imgsz 64 --batch 32 --weights runs/train/exp/weights/best.pt --device cpu
   python detect.py --imgsz 64 --weights yolov3-tiny.pt --device cpu

5. Create a pull request: Open a PR from your branch to the master branch of ultralytics/yolov3. Provide a clear title and a description explaining the purpose and scope of your changes.

PR Best Practices

To ensure your contribution is integrated smoothly, please:

- ✅ Keep your PR up-to-date with the master branch. If it falls behind, click the 'Update branch' button or merge master locally.
- ✅ Confirm that all Continuous Integration (CI) checks pass.
- ✅ Limit changes to the minimum required for your bug fix or feature.
_"It is not daily increase but daily decrease, hack away the unessential. The closer to the source, the less wastage there is."_ — Bruce Lee

🎨 Code Style and Formatting

Ultralytics YOLOv3 is formatted with Ruff using a line length of 120 (configured in pyproject.toml). When you open a PR, the Ultralytics Actions bot automatically applies formatting — Ruff, docformatter, codespell, and prettier — so there is no need to fight its style. New functions and classes should include Google-style docstrings so the codebase stays readable and maintainable.

📝 CLA Signing

Before we can merge your pull request, you must sign our Contributor License Agreement (CLA). This legal agreement ensures that your contributions are properly licensed, allowing the project to continue being distributed under the AGPL-3.0 license.

After you submit your PR, the CLA bot will guide you through the signing process. To sign, add a comment in your PR stating:

text

I have read the CLA Document and I sign the CLA

🐛 Submitting a Bug Report

If you encounter an issue with Ultralytics YOLOv3, please submit a bug report!

To help us investigate, please provide a minimum reproducible example. Your code should be:

- ✅ Minimal – Use as little code as possible that still produces the issue.
- ✅ Complete – Include all parts needed for someone else to reproduce the problem.
- ✅ Reproducible – Test your code to ensure it reliably triggers the issue.

Additionally, for Ultralytics to assist, your code should be:

- ✅ Current – Verify the problem persists on the latest master branch. Use git pull or git clone to get the latest version.
- ✅ Unmodified – The problem must be reproducible without custom modifications. Ultralytics does not provide support for custom code.

If your issue meets these criteria, please open a new issue using the 🐛 Bug Report template, including your minimum reproducible example to help us diagnose and resolve the problem.

📜 License

By contributing, you agree that your submissions will be licensed under the AGPL-3.0 license.

---

Thank you for helping improve Ultralytics YOLOv3! Your contributions make a difference. For more on open-source best practices, see GitHub's open source guides.

---

README

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.

📚 Documentation

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

<details open>
<summary>Install</summary>

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

bash

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

</details>

<details open>
<summary>Inference with PyTorch Hub</summary>

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

python

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

</details>

<details>
<summary>Inference with detect.py</summary>

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

bash

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

</details>

<details>
<summary>Training</summary>

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

bash

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.

</details>

<details>
<summary>Tutorials</summary>

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

- Train Custom Data — train on your own dataset.
- Tips for Best Training Results — get the most out of training.
- Multi-GPU Training — scale training across GPUs.
- PyTorch Hub Loading — load models programmatically.
- Model Export — deploy to ONNX, TensorRT, CoreML, and more.
- Test-Time Augmentation (TTA) — improve accuracy at inference.
- Model Ensembling — combine models for better results.
- Hyperparameter Tuning — tune hyperparameters automatically.
- Transfer Learning with Frozen Layers — adapt pretrained models efficiently.

</details>

🧠 Architecture

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

- Darknet-53 backbone — a 53-layer convolutional feature extractor with residual (skip) connections, deeper and more accurate than the Darknet-19 backbone of YOLOv2 while staying efficient.
- Multi-scale detection — predictions are made at three feature-map scales using a feature-pyramid-style design (upsampling and concatenating earlier feature maps), so the model detects small, medium, and large objects well.
- Anchor boxes — boxes are predicted relative to dimension-cluster anchor priors, with three anchors per scale (nine total) and a sigmoid offset parameterization for stable training.
- Independent class prediction — each class is scored with an independent logistic classifier rather than a softmax, so one box can carry multiple non-mutually-exclusive labels.

The repository ships three variants of this architecture:

- YOLOv3 — the full Darknet-53 model; the best balance of speed and accuracy.
- YOLOv3-SPP — adds a Spatial Pyramid Pooling block that pools features at multiple kernel sizes for a larger effective receptive field and a small accuracy gain.
- YOLOv3-tiny — a compact backbone with detection at two scales, optimized for CPU and edge devices where speed matters most.

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.

🤔 Why YOLOv3?

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

- Real-time single-stage detection — one forward pass produces all detections, with no separate region-proposal stage.
- Strong across object sizes — multi-scale predictions handle small, medium, and large objects.
- Multi-label friendly — independent logistic classifiers allow overlapping class labels.
- Simple and portable — a fully-convolutional design that trains and exports cleanly to many deployment formats.

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.

🤝 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!

[](https://github.com/ultralytics/yolov3/graphs/contributors)

📜 License

Ultralytics offers two licensing options:

- AGPL-3.0 License: An OSI-approved open-source license ideal for research and collaboration. See the LICENSE file for details.
- Enterprise License: For commercial use, this license allows integration of Ultralytics software and models into commercial products without AGPL-3.0 obligations. Contact us via Ultralytics Licensing.

📧 Contact

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

---

CONTRIBUTING Copy Section

Contributing to Ultralytics YOLOv3 🚀

🚀 Submitting a Pull Request (PR) Copy Chapter

PR Best Practices Copy Section

🎨 Code Style and Formatting Copy Chapter

📝 CLA Signing Copy Chapter

🐛 Submitting a Bug Report Copy Chapter

📜 License Copy Chapter

README Copy Section

📚 Documentation Copy Chapter

Clone the YOLOv3 repository

Navigate to the cloned directory

Install required packages

Load a YOLOv3 model (choices: 'yolov3', 'yolov3_spp', 'yolov3_tiny')

Run inference on an image (local file, URL, PIL image, OpenCV frame, or numpy array)

Inspect the results

Train YOLOv3-tiny

Train YOLOv3

Train YOLOv3-SPP

🧠 Architecture Copy Chapter

🏋️ Pretrained Checkpoints Copy Chapter

🧩 Integrations Copy Chapter

🤔 Why YOLOv3? Copy Chapter

☁️ Environments Copy Chapter

🤝 Contribute Copy Chapter

📜 License Copy Chapter

📧 Contact Copy Chapter

Explore Related Technologies & Topics

CONTRIBUTING

🚀 Submitting a Pull Request (PR)

PR Best Practices

🎨 Code Style and Formatting

📝 CLA Signing

🐛 Submitting a Bug Report

📜 License

README

📚 Documentation

🧠 Architecture

🏋️ Pretrained Checkpoints

🧩 Integrations

🤔 Why YOLOv3?

☁️ Environments

🤝 Contribute

📜 License

📧 Contact