keras-YOLOv3-model-set: a YOLO detection pipeline rebuilt on tf.keras

A pipeline inherited from keras-yolo3 and YAD2K, not written from scratch

The project describes itself as a general YOLOv4, v3 and v2 object detection pipeline, implemented on tf.keras with different technologies, and it says plainly where it comes from: it is inherited from keras-yolo3-Mobilenet and keras-yolo3, and from YAD2K.

That lineage explains the shape of the repository. The top level has separate directories for each generation of the network, yolo2, yolo3, yolo4 and yolo5, plus scaled_yolo4 for the Scaled YOLOv4 variant, a common directory for shared code, and a tools directory. Inside tools sits the model_converter, which is the piece that turns a Darknet checkpoint into a Keras model. There is a cfg directory holding the Darknet configuration files that the converter reads, a weights directory where the checkpoints are expected to land, a configs directory, an inference directory, a tracking directory, an example directory with sample images, and a Dockerfile for a CUDA environment.

The scope is stated as covering the whole lifecycle: data collection and annotation, model training and tuning, model evaluation, and on-device deployment.

The audience is therefore someone doing research or teaching on object detection who wants the classic YOLO training loop in a framework they can read, and who wants to swap components. This is a laboratory bench rather than a product, and the license is MIT, which makes the fork-and-modify path unencumbered.

The last push was on 2026-08-01 and the repository is not archived, so the code is still reachable, but the most recent release tag visible is v1.3.0 from 2021-05-01, with v1.2.0 in May 2020 and v1.1.0 in March 2020. That gap between the last release and the last commit is the single most important fact for an adopter, and it comes back in the maintenance section.

The component matrix: eleven backbones, seven heads, nine losses

The README is organised as a set of checkboxes, and reading it as a matrix is the fastest way to understand what this project is.

For backbones there are eleven: CSPDarknet53, Darknet53 and Tiny Darknet, Darknet19, MobileNetV1, MobileNetV2, MobileNetV3 in both Large and Small sizes, PeleeNet, GhostNet, EfficientNet, Xception and VGG16. The heavy backbones and the mobile ones sit in the same list, which is the point, because the pipeline lets you train a large model on a GPU and deploy a small one on a phone.

For heads there are seven, covering YOLOv4 and a Lite version, Tiny YOLOv4 marked as no-SPP and unofficial, YOLOv3 Lite with SPP, YOLOv3 Nano marked unofficial, Tiny YOLOv3 Lite and YOLOv2 Lite and Tiny YOLOv2 Lite.

For losses there are nine entries: the YOLOv3 and YOLOv2 losses, binary and softmax focal classification loss, GIoU localization loss, DIoU and CIoU localization loss, SIoU localization loss, an experimental binary focal loss for objectness, and label smoothing for classification loss. The DIoU, CIoU and SIoU entries each link to the paper that introduced them.

The training techniques list transfer training from imagenet, single-scale and multi-scale image input training, dynamic learning rate decay with Cosine, Exponential, Polynomial and PiecewiseConstant schedules, weights averaging policies for the optimizer including EMA, SWA and Lookahead, Mosaic data augmentation, GridMask augmentation, multi anchors for a single ground truth, pruned model training, and multi-GPU training with SyncBatchNorm support.

Two of those carry explicit caveats in the README text. Pruned model training is marked as only valid for TF 1.x, and the weights averaging entry is marked as valid for TF-2.x with tfa. That level of annotation is a good sign, since it tells you which combinations of the matrix are actually exercised.

Postprocessing is where the variants pile up, in NumPy, C++ and TFLite

The postprocess section is the largest and most interesting list, because it separates the implementations by where they run.

There is a NumPy implementation of YOLOv3 and v2 postprocessing, a TFLite and MNN C++ implementation of the same, and a tf.keras batch-wise YOLOv3 and v2 postprocess layer. On top of that sit the non-maximum suppression variants: DIoU-NMS in both NumPy and C++, SoftNMS in NumPy, and the Cluster NMS family covering Fast, Matrix, SPM and Weighted variants.

Two more entries are about fixing the model rather than the output. Eliminate grid sensitivity is listed as implemented in NumPy and C++ and is credited to YOLOv4. And WBF, Weighted-Boxes-Fusion, is implemented in NumPy and links to its paper.

The reason there are three implementations of the same postprocessing is worth spelling out, because it is a genuine architectural constraint rather than duplication for its own sake. A Keras training pipeline keeps everything as tensors in a graph. A deployed TFLite or MNN model cannot run arbitrary NumPy at inference time in the same way, so the decode step has to exist in a form the target runtime can execute. That is why the C++ variant exists alongside the Python one, and it is why the tf.keras batch-wise layer exists as a third option for the case where you want postprocessing inside the graph.

The same reasoning applies to the deployment section, which lists Tensorflow-Lite Float32 and UInt8 model inference, and MNN Float32 and UInt8 model inference. UInt8 quantisation is a separate path from Float32, not a flag, which is the usual sign that a model has actually been taken through a quantisation-aware training and conversion flow rather than converted after the fact.

Setting up: pinned dependencies, Darknet weights, and a conversion step

The quick start is four steps, and step one is the dependency install on Ubuntu 22.04 or 24.04 with Python 3.10:

# apt install python3-opencv imagemagick
# pip install Cython
# pip install -r requirements.txt

Step two is downloading the Darknet, YOLOv2, v3 and v4 weights from the YOLO website and from the AlexeyAB darknet repository. Step three is converting the Darknet model into a Keras model, and step four is running detection on an image or video, by default with the Tiny YOLOv3 model.

The conversion is a script in the tools directory that takes a cfg file, a weights file and an output path:

# python tools/model_converter/convert.py cfg/yolov3.cfg weights/yolov3.weights weights/yolov3.h5
# python tools/model_converter/convert.py cfg/yolov3-tiny.cfg weights/yolov3-tiny.weights weights/yolov3-tiny.h5

Two variants of the converter call exist. YOLOv4 needs its output tensors reordered, and the README includes a comment saying to make sure to reorder output tensors for the YOLOv4 cfg and weights file, which is what the yolo4_reorder flag does. Scaled YOLOv4 uses the same flag with a different cfg and weights file. And the Yolo-Fastest models use the plain converter with their own cfg and weights.

Two of the weight files cannot be fetched with wget and the README says so explicitly: csdarknet53-omega_final.weights and yolov4-csp.weights have to be downloaded manually from Google Drive links. Two of the Google Drive links in the README are not the direct download URLs, which is why the text says to download them manually.

Running detection is one command, and the README notes that for other models you do the same thing with different model type, weights path and anchor path flags.

The pinned dependency set dates the project more precisely than the dates do

The requirements file is the most informative document in the repository, and it is worth reading closely.

It pins scikit-learn at 0.20.3, opencv-python and opencv-contrib-python at 4.2.0.32, tensorflow at 2.11.0, tensorflow-model-optimization at 0.5.0, and bokeh at 2.4.0. Everything else is unpinned: numpy, setuptools, scipy, keras_applications, tensorflow-addons, matplotlib, tqdm, pillow, mnn, pycocotools, keras2onnx, tf2onnx, onnx, onnxruntime, tfcoreml, sympy, imgaug, imagecorruptions, tidecv, and Cython.

That list also tells you what the project can do beyond Keras inference. keras2onnx and tf2onnx with onnx and onnxruntime cover the ONNX export and runtime path, and tfcoreml covers the Core ML path for Apple platforms, which is a reasonable set of targets for a project that has been used for edge deployment work.

The pinning is the risk. TensorFlow 2.11 is a specific generation, and pairing it with Python 3.10 on a current Ubuntu is the combination the quick start describes. Meanwhile scikit-learn 0.20.3 and opencv 4.2.0.32 are old enough that installing them into a modern environment alongside other work is likely to conflict, which is why the project ships a Dockerfile rather than only a requirements file.

That Dockerfile is built on a CUDA base image, with arguments for the Ubuntu version, architecture, CUDA 10.0 and cuDNN 7.4.1.5, and it sets the TensorFlow environment variables including TF_CUDA_COMPUTE_CAPABILITIES, TF_CUDA_VERSION and TF_CUDNN_VERSION. The CUPTI and cuDNN library paths are added to LD_LIBRARY_PATH. It also deletes the static cuDNN archives from the image, which is a deliberate space saving.

Note the mismatch between the Dockerfile base, which defaults to Ubuntu 18.04 and CUDA 10.0, and the quick start, which says Ubuntu 22.04 or 24.04 with Python 3.10. The container is for the training side with an old CUDA stack, and the quick start is for a modern local environment.

Where keras-YOLOv3-model-set is the wrong tool

The first wrong-tool case is a new production detection service. The pinned TensorFlow 2.11, scikit-learn 0.20.3 and OpenCV 4.2.0.32 belong to an earlier era, and the last release tag is from 2021. A team shipping a detector today will spend its first week fighting the environment, and that week is not spent on detection.

The second is a requirement for a current detector. The checklist covers YOLOv2, v3, v4, YOLOv3 Nano, Scaled YOLOv4 and Yolo-Fastest. It does not cover the YOLO generations that followed, and the README does not claim it does. If you need a recent architecture, this repository will not get you there.

The third is a deployment-first problem. The on-device path is TFLite and MNN, with ONNX and Core ML also in the dependency list. If your target is a different accelerator runtime, or a server-side serving stack, the export path is not here.

The fourth is a team that wants a maintained library rather than a research pipeline. This is code laid out for reading and modifying: cfg files, a conversion script, per-version directories and a long matrix of options. The value is in the fact that you can change the backbone, the head or the loss and see what happens. The cost is that there is no stable API to depend on, and the training entry points are scripts rather than a packaged interface.

The fifth is a beginner. The quick start assumes you know what a cfg file is, that Darknet weights are a separate download, and that the Keras model is produced by a conversion step rather than trained from scratch. The repository ships a Getting Started style example only for the Keras model set itself, and the sample images in the example directory are there to show detection output rather than to walk a newcomer through the pipeline.

Maintenance, licensing and the gap between the tags and the commits

The maintenance picture is mixed and worth stating precisely.

The repository is not archived and the last push was on 2026-08-01, so the code is present and reachable. The most recent releases are v1.3.0 from 2021-05-01, v1.2.0 from 2020-05-22 and v1.1.0 from 2020-03-22. There is a CHANGELOG-less top level, so the commit history is the record of what changed and when, and the release tags stopped moving five years before the last commit.

The licence is MIT, with the LICENSE file at the repository root and a licence badge in the README. For a research pipeline that people fork, extend and publish papers with, MIT removes essentially every question about reuse, and that is a genuine strength of the project. It also means the improvement burden sits with whoever forks it.

The repository has a .gitignore, a Dockerfile, a cfg directory, configs, and an assets directory with sample output images. The directories named yolo2 through yolo5 suggest the generations accumulate rather than replace, which is another way of saying the codebase is a growing archive of model variants rather than a single maintained package.

My honest assessment is that this is a well-organised research codebase at the end of its active development, whose value is that the components are separable and the training recipes are legible. If you need to reproduce or extend a classic YOLO experiment, it saves you a lot of assembly. If you need a detector you can deploy and upgrade next year, you start somewhere else.

Editorial conclusion

keras-YOLOv3-model-set fits a researcher or student who wants to train or fine-tune a classic YOLO detector in Keras, reproduce a paper's training recipe, or export a model to TFLite or MNN for on-device inference. It is the wrong choice for a production system starting today, since the pinned TensorFlow, scikit-learn and OpenCV versions belong to an earlier era and the last release was in 2021. Before adopting it, check the pinned versions in requirements.txt against your own environment, confirm that the specific backbone and loss combination you need is on the checklist, and expect to spend time on the model conversion step, which requires downloading Darknet weights separately.

Frequently asked questions

Official sources

1. david8862/keras-YOLOv3-model-set on GitHub
2. Issues
3. License: MIT
4. README
5. Releases