### 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](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests). To make the review process as smooth as possible, please follow these steps: 1. **[Fork the repository](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo):** Fork [ultralytics/yolov3](https://github.com/ultralytics/yolov3) to your GitHub account. 2. **[Create a branch](https://docs.github.com/en/desktop/making-changes-in-a-branch/managing-branches-in-github-desktop):** 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](https://github.com/ultralytics/yolov3/blob/master/.github/workflows/ci-testing.yml) 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](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request):** Open a PR from your branch to the `master` branch of [ultralytics/yolov3](https://github.com/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](https://github.com/astral-sh/ruff) using a line length of 120 (configured in `pyproject.toml`). When you open a PR, the [Ultralytics Actions](https://github.com/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](https://google.github.io/styleguide/pyguide.html) so the codebase stays readable and maintainable. ## πŸ“ CLA Signing Before we can merge your pull request, you must sign our [Contributor License Agreement (CLA)](https://docs.ultralytics.com/help/CLA). This legal agreement ensures that your contributions are properly licensed, allowing the project to continue being distributed under the [AGPL-3.0 license](https://www.ultralytics.com/legal/agpl-3-0-software-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](https://docs.ultralytics.com/help/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](https://www.ultralytics.com/) to assist, your code should be: - βœ… **Current** – Verify the problem persists on the latest [`master` branch](https://github.com/ultralytics/yolov3/tree/master). Use `git pull` or `git clone` to get the latest version. - βœ… **Unmodified** – The problem must be reproducible without custom modifications. [Ultralytics](https://www.ultralytics.com/) does not provide support for custom code. If your issue meets these criteria, please open a new issue using the πŸ› **Bug Report** [template](https://github.com/ultralytics/yolov3/issues/new/choose), including your [minimum reproducible example](https://docs.ultralytics.com/help/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](https://www.ultralytics.com/legal/agpl-3-0-software-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](https://opensource.guide/how-to-contribute/). --- ### README

Ultralytics YOLOv3 banner

[δΈ­ζ–‡](https://docs.ultralytics.com/zh) | [ν•œκ΅­μ–΄](https://docs.ultralytics.com/ko) | [ζ—₯本θͺž](https://docs.ultralytics.com/ja) | [Русский](https://docs.ultralytics.com/ru) | [Deutsch](https://docs.ultralytics.com/de) | [FranΓ§ais](https://docs.ultralytics.com/fr) | [EspaΓ±ol](https://docs.ultralytics.com/es) | [PortuguΓͺs](https://docs.ultralytics.com/pt) | [TΓΌrkΓ§e](https://docs.ultralytics.com/tr) | [TiαΊΏng Việt](https://docs.ultralytics.com/vi) | [Ψ§Ω„ΨΉΨ±Ψ¨ΩŠΨ©](https://docs.ultralytics.com/ar)
YOLOv3 CI YOLOv3 Citation Docker Pulls Discord Ultralytics Forums Ultralytics Reddit
Open In Colab

[Ultralytics](https://www.ultralytics.com/) YOLOv3 is a PyTorch implementation of the YOLOv3 (You Only Look Once, version 3) real-time [object detection](https://docs.ultralytics.com/tasks/detect) 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`](https://github.com/ultralytics/ultralytics) package. Find detailed guidance in the [Ultralytics YOLOv3 Docs](https://docs.ultralytics.com/models/yolov3). Get support via [GitHub Issues](https://github.com/ultralytics/yolov3/issues/new/choose), and join the conversation on [Discord](https://discord.com/invite/ultralytics), [Reddit](https://www.reddit.com/r/ultralytics/), and the [Ultralytics Forums](https://community.ultralytics.com/). For commercial use, request an Enterprise License at [Ultralytics Licensing](https://www.ultralytics.com/license).
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](https://docs.ultralytics.com/models/yolov3) 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**](https://www.python.org/) environment with [**PyTorch>=1.8**](https://pytorch.org/get-started/locally/). ```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 ```
Inference with PyTorch Hub Load YOLOv3 directly through [PyTorch Hub](https://docs.ultralytics.com/yolov5/tutorials/pytorch_hub_model_loading). 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 ```
Inference with detect.py `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 ```
Training Train YOLOv3 on the [COCO](https://docs.ultralytics.com/datasets/detect/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`.
Tutorials These guides cover the shared Ultralytics training framework and apply to YOLOv3: - [Train Custom Data](https://docs.ultralytics.com/modes/train) β€” train on your own dataset. - [Tips for Best Training Results](https://docs.ultralytics.com/guides/model-training-tips) β€” get the most out of training. - [Multi-GPU Training](https://docs.ultralytics.com/yolov5/tutorials/multi_gpu_training) β€” scale training across GPUs. - [PyTorch Hub Loading](https://docs.ultralytics.com/yolov5/tutorials/pytorch_hub_model_loading) β€” load models programmatically. - [Model Export](https://docs.ultralytics.com/modes/export) β€” deploy to ONNX, TensorRT, CoreML, and more. - [Test-Time Augmentation (TTA)](https://docs.ultralytics.com/yolov5/tutorials/test_time_augmentation) β€” improve accuracy at inference. - [Model Ensembling](https://docs.ultralytics.com/yolov5/tutorials/model_ensembling) β€” combine models for better results. - [Hyperparameter Tuning](https://docs.ultralytics.com/guides/hyperparameter-tuning) β€” tune hyperparameters automatically. - [Transfer Learning with Frozen Layers](https://docs.ultralytics.com/yolov5/tutorials/transfer_learning_with_frozen_layers) β€” adapt pretrained models efficiently.
## 🧠 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`](https://github.com/ultralytics/yolov3/tree/master/models) 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](https://docs.ultralytics.com/datasets/detect/coco) (80 classes) and download automatically from the [YOLOv3 release assets](https://github.com/ultralytics/yolov3/releases) on first use. | Model | Description | | ----------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | | [yolov3-tiny.pt](https://github.com/ultralytics/yolov3/releases/download/v9.6.0/yolov3-tiny.pt) | Lightweight two-scale model β€” the fastest option, ideal for CPU and edge devices. | | [yolov3.pt](https://github.com/ultralytics/yolov3/releases/download/v9.6.0/yolov3.pt) | The original Darknet-53 model β€” a strong balance of speed and accuracy. | | [yolov3-spp.pt](https://github.com/ultralytics/yolov3/releases/download/v9.6.0/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](https://docs.ultralytics.com/integrations/weights-biases), [Comet ML](https://docs.ultralytics.com/integrations/comet), [Roboflow](https://docs.ultralytics.com/integrations/roboflow), and [Intel OpenVINO](https://docs.ultralytics.com/integrations/openvino) can streamline your workflow at [Ultralytics Integrations](https://docs.ultralytics.com/integrations). Ultralytics active learning 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](https://github.com/ultralytics/ultralytics). ## ☁️ 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](https://docs.ultralytics.com/help/contributing) to get started, and share your feedback through the [Ultralytics Survey](https://www.ultralytics.com/survey?utm_source=github&utm_medium=social&utm_campaign=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](https://opensource.org/license/agpl-3.0) open-source license ideal for research and collaboration. See the [LICENSE](https://github.com/ultralytics/yolov3/blob/master/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](https://www.ultralytics.com/license). ## πŸ“§ Contact For bug reports and feature requests, please use [GitHub Issues](https://github.com/ultralytics/yolov3/issues). For questions and discussion, join our [Discord](https://discord.com/invite/ultralytics), [Reddit](https://www.reddit.com/r/ultralytics/), and the [Ultralytics Forums](https://community.ultralytics.com/).
Ultralytics GitHub space Ultralytics LinkedIn space Ultralytics Twitter space Ultralytics YouTube space Ultralytics TikTok space Ultralytics BiliBili space Ultralytics Discord
---