# ultralytics/xview-yolov3: training YOLOv3 on xView satellite imagery

> A small Ultralytics repository that packages the training, preprocessing and inference scripts for YOLOv3 on the xView detection challenge. The pipeline is honest about its numbers: 0.16 validation mAP after 300 epochs, and a documented overfitting wall near 200 epochs.

**ultralytics/xview-yolov3** — YOLOv3 training, preprocessing, validation, and inference for object detection in xView satellite imagery and the xView detection challenge.

- Repository: https://github.com/ultralytics/xview-yolov3
- Website: https://docs.ultralytics.com
- Stars: 347 · Forks: 59
- Language: Python
- License: AGPL-3.0
- Published: 2026-09-17 · Updated: 2026-09-17 · Language: en
- Canonical page: https://hysenlabs.com/projects/ultralytics-xview-yolov3

## What xview-yolov3 actually covers, and who it is for

The repository is a task-specific packaging of YOLOv3 for one dataset. The README states the primary goal directly: to support participants in the xView Challenge, which focuses on detecting objects in satellite imagery. That framing matters, because it tells you the intended user is a challenge entrant, not someone who wants a general detection library. The code covers four stages: preprocessing of labels, training, validation, and inference, with detect.py and train.py as the two entry points and a scoring/ directory alongside them. The xView dataset itself comes from the challenge data download page, not from the repository, and the README warns that satellite imagery datasets can be quite large. If you already have a YOLOv3 pipeline and only need the xView-specific pieces, the value here is the label preprocessing and the anchor configuration rather than the model code, which is standard YOLOv3. If you have never trained a detector before, this is a poor starting point: nothing in the README walks through dataset layout in detail, and the training script expects you to edit paths before anything runs.

## How the xView preprocessing and anchor generation fit together

Two preprocessing steps sit between the raw xView labels and a training run. The first is outlier removal using sigma-rejection, which cleans the target labels before they reach the model. The second is anchor generation: a new set of 30 k-means anchors is produced specifically for the c60_a30symmetric.cfg configuration file, and the README points at the MATLAB script utils/analysis.m for that job. That is an unusual dependency for a Python project, and it is worth flagging plainly. Anyone without MATLAB access cannot regenerate anchors through the documented route, even though the resulting configuration and the anchor plot at cfg/c60_a30.png are checked into the repository. The training loop itself samples 8 random 800x800 pixel chips from each full-resolution image per epoch, with -img_size defaulting to 32 x 25, which is 800. Augmentation is applied in datasets.py through OpenCV, and the README is explicit that it runs only during training: inference and validation use the original, unaugmented images, and bounding box coordinates are adjusted to match whatever transformation was applied. The augmentation table gives concrete ranges, including rotation of plus or minus 20 degrees, scale of plus or minus 30 percent, and reflection at 50 percent probability on both axes.

## Installing xview-yolov3 and running a first training job

The README requires Python 3.6 or later and recommends a virtual environment. Dependencies install from the requirements file, which lists numpy, scipy, opencv-python, torch, matplotlib, tqdm and h5py.

```bash
pip3 install -U -r requirements.txt
```

After that you download the xView data from the challenge data download page and place it where the training script expects it. The README does not spell out the directory name, so read train.py before you move anything. Then set the train_path values in train.py for your machine or your cloud environment; the README names Google Colab and Kaggle as options.

```bash
python train.py
```

If a run is interrupted, resume from the last checkpoint with the -resume flag. The README states the script loads weights from weights/latest.pt and continues.

```bash
python train.py -resume 1
```

Expect a long run. The README reports that on an Nvidia GTX 1080 Ti you can typically complete around 100 epochs per day, so the 300-epoch experiment that produced the best validation mAP took roughly three days. Watch the loss plots for bounding box regression, objectness and class confidence; they should trend downward.

## The overfitting wall and the mAP ceiling

The README is unusually candid about results, and that candour is the most useful thing in it. The best observed validation mAP in the documented experiments was 0.16 after 300 epochs, against a training mAP of 0.30. That gap is the headline limitation. Roughly half the training-set performance does not transfer to validation, and the README states that overfitting can become a significant issue after approximately 200 epochs. So the practical operating window is narrow: train long enough to converge, stop before the validation curve turns. Anyone expecting a satellite detector that drops into production from these scripts should recalibrate. A 0.16 mAP is a research baseline, not a deliverable model, and the README presents it as the outcome of an experiment rather than a target. The other constraint is hardware. The throughput figure of about 100 epochs per day is tied to a GTX 1080 Ti, and nothing in the README suggests a faster path. Budget three days of GPU time minimum for a run comparable to the one described, plus the time to download and stage the imagery.

## Where this is the wrong tool

Three cases where you should look elsewhere. First, general object detection on ordinary photographs: nothing here is specialized for that, and the preprocessing exists to handle xView label quirks you will not have. Second, anyone who needs a maintained framework with regular releases. The repository is not archived and the last push was on 2026-08-28, but the only release listed is v0 from 2019-04-04, so the versioned surface has not moved in years and the training recipe is tied to that era of YOLOv3. Third, teams that cannot accept AGPL-3.0 terms. The licence is a real constraint on how the code can be redistributed or offered as a network service, and the repository ships no alternative licensing path in the files listed. A further soft limitation: the anchor generation step depends on a MATLAB script, so if your class distribution differs from xView's and you want tailored anchors, the documented route assumes a MATLAB licence.

## How it differs from YOLOv5 and the wider Ultralytics tooling

The obvious alternative is the newer Ultralytics line, in particular YOLOv5, which the same organization maintains. The difference is not just architecture. YOLOv5 ships an integrated training pipeline with a single command-line entry point, dataset configuration through YAML files, and export tooling, so you rarely edit Python source to point at your data. Here you edit train_path inside train.py, and preprocessing is a separate manual stage involving sigma-rejection and a MATLAB anchor script. The xview-yolov3 repository is closer to a research snapshot: it documents one dataset, one configuration (c60_a30symmetric.cfg), and the results of one set of experiments. If your goal is the xView challenge specifically, that narrowness is a feature, because the anchor set and label cleaning are already tuned for these images. If your goal is a detector you will retrain repeatedly on changing data, the manual path editing and the MATLAB dependency will cost you more time than they save.

## Maintenance, licence and upgrade cost

The last push was on 2026-08-28, so the repository is not abandoned, but the release history is thin: v0, dated 2019-04-04, is the only release listed. Treat the code as stable rather than evolving. Upgrading is therefore mostly about your environment, not the project: Python 3.6 or later is the stated floor, and the requirements file pins nothing, so a fresh install pulls current numpy, scipy, torch, opencv-python, matplotlib, tqdm and h5py. Unpinned deep learning dependencies are a known source of breakage when APIs shift, and the README does not document a tested dependency set beyond the file itself. On licensing, AGPL-3.0 is a copyleft licence with network-use provisions. If you plan to expose a trained service to users over a network, read the licence text and get your own advice; nothing in the repository offers a commercial exception, and this article is not legal advice.

## Conclusion

Adopt it if you are entering the xView challenge or need a working YOLOv3 baseline on satellite chips and can accept a validation mAP around 0.16 and roughly three days of training on a GTX 1080 Ti. Do not adopt it for general-purpose detection on ordinary photographs, for a maintained framework with rolling releases, or if AGPL-3.0 licensing does not fit your deployment. Before committing, verify three things: that the xView download is complete and placed where train.py expects it, that the 30 k-means anchors in c60_a30symmetric.cfg match the class count you intend to train, and that you can reproduce the -resume 1 path from weights/latest.pt after an interrupted run.

## FAQ

### Which YOLO version is best for object detection?

The README does not rank YOLO versions. This repository trains YOLOv3 specifically, and it reports a best validation mAP of 0.16 after 300 epochs on xView, with overfitting becoming significant after roughly 200 epochs.

### Is YOLO free to use?

This repository is licensed under AGPL-3.0, which is a copyleft licence with network-use provisions. Whether that fits your use depends on how you distribute or host the software, and the repository offers no alternative licensing path.

### What architecture does YOLO use?

The README describes this project as training the Ultralytics YOLOv3 object detection model, configured through c60_a30symmetric.cfg with 30 k-means anchors generated for the xView dataset. It does not detail the internal layer structure.

### Is YOLO an AI model?

The README refers to YOLOv3 as an object detection model trained with PyTorch, and lists torch among the key dependencies. It does not otherwise discuss how to categorize the model.

## Sources

- [License: AGPL-3.0](https://github.com/ultralytics/xview-yolov3/blob/main/LICENSE)
- [Project website](https://docs.ultralytics.com)
- [README](https://github.com/ultralytics/xview-yolov3/blob/main/README.md)
- [Releases](https://github.com/ultralytics/xview-yolov3/releases)
- [ultralytics/xview-yolov3 on GitHub](https://github.com/ultralytics/xview-yolov3)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/ultralytics-xview-yolov3