PaddleDetection: a config-driven detection toolkit with industrial PP models, old pinned dependencies and a quick start that leads to PaddleX

Detectors are assembled from decoupled modules chosen in config files

The core idea is modular design: PaddleDetection splits a detection model into separate components, and you build a detector by combining them rather than writing a model from scratch. The library code lives in ppdet/, model definitions are selected through files under configs/, and deployment code sits in deploy/. To understand what each config field does, the project points to two annotated examples, docs/tutorials/config_annotation/faster_rcnn_r50_fpn_1x_coco_annotation.md for an RCNN model and ppyolo_r50vd_dcn_1x_coco_annotation.md for PP-YOLO. Adding a new architecture is covered in docs/advanced_tutorials/MODEL_TECHNICAL.md, and the data pipeline in docs/advanced_tutorials/READER.md. The model zoo spans 2D and 3D detection, instance segmentation, face detection, keypoint detection, multi-object tracking and semi-supervised learning. The consequence of this design is that most of your work happens in configuration files: once you learn the annotated RCNN and PP-YOLO examples you can swap components, but you are working inside PaddleDetection's own conventions rather than plain PaddlePaddle code.

The PP model families each target one industrial job

Beyond generic baselines, the toolkit ships its own named models. PP-YOLOE and PP-YOLOE+ handle high-accuracy general detection. PP-YOLOE-R detects rotated boxes, and PP-YOLOE-SOD focuses on small objects. PP-PicoDet is the ultra-lightweight real-time detector, and the model zoo compares server-side and mobile-side models separately. PP-Tracking is a real-time multi-object tracking system, and PP-TinyPose detects human skeleton keypoints. Two higher-level tools sit on top: PP-Human covers intrusion detection, behavior analysis, attribute analysis and people counting, while PP-Vehicle covers license plate recognition, traffic flow counting, traffic violation detection and vehicle attributes. The vehicle pipeline lives under deploy/pipeline/ppvehicle, which is why requirements.txt pulls in pyclipper. For RT-DETR, the project claims it is a real-time detector that surpasses YOLOv8 in accuracy, and an instance segmentation variant, Mask-RT-DETR, was added later. 3D detection is not in this repository at all: its tile links out to the separate Paddle3D project. The industrial_tutorial/ directory holds worked examples for industry, agriculture, forestry, transport, healthcare, finance and energy.

The quick start hands you off to PaddleX

The quick start and low-code sections of the README do not start a PaddleDetection script. They link to docs/paddlex/quick_start.md and docs/paddlex/overview.md, which describe PaddleX, the PaddlePaddle low-code tool built on PaddleDetection. Since the 2024.10.1 update, PaddleX groups 55 models for general detection, small object detection and instance segmentation into 3 model pipelines called through a Python API, and the same API covers more than 200 models across over 20 single-function modules, including image classification, segmentation, OCR and time series forecasting. PaddleX offers a unified command and a graphical interface, supports high-performance, service-based and edge deployment, and lists NVIDIA GPU, Kunlunxin, Ascend, Cambricon and Hygon hardware. The Mask-RT-DETR link even points into PaddleX's release/3.0-beta1 documentation. The cost for a reader is a fork in the road on day one: you must decide whether you want PaddleDetection's config-level control or PaddleX's one-call pipelines, and the README's first steps lean toward the second.

Pinned dependencies keep it on numpy 1.x and OpenCV 4.6 or older

requirements.txt sets several hard ceilings and exact pins: numpy < 2.0, opencv-python <= 4.6.0, pycocotools==2.0.8 and sklearn==0.0, alongside an unpinned scikit-learn. It also requires visualdl>=2.2.0 for training visualization and imgaug>=0.4.0 for CULane data augmentation, plus lapx and motmetrics for tracking evaluation. These ceilings are where adoption gets expensive. If your environment already holds numpy 2 or a newer opencv-python, pip has to downgrade them or refuse to resolve, and anything else in that environment that needs the newer versions breaks. The safe approach is a dedicated virtual environment for PaddleDetection alone. Installation itself is not a single command in the README; it sends you to docs/tutorials/INSTALL_cn.md. Cython and shapely are also on the list.

setup.py stamps every source build as version 0.0.0

setup.py hard-codes PPDET_VERSION = "0.0.0" and, at install time, writes ppdet/version.py with that version and the current commit hash from git rev-parse HEAD. If the git call raises an error, for example because git is not installed, the bare except clause records the commit as Unknown. The practical effect is that a source install reports 0.0.0 no matter whether you checked out the v2.9.0 tag from 2026-03-19, v2.8.1 from 2025-02-14 or v2.8.0 from 2024-11-08. If you need to know which release produced a model, the version string will not tell you; record the tag or commit yourself, and keep the .git directory so the commit field is filled in. The same file reads README.md for the package description and parses requirements from a text file, so the pins above carry straight into a setup.py install.

The default branch is release/2.9, while some links point at develop

The repository's default branch is release/2.9, matching the v2.9.0 release. Yet the RT-DETR code link in the README goes to configs/rtdetr on the develop branch. Code reached through that link can differ from what ships on release/2.9, so before copying a config, check which branch you are on and whether the same path exists in your checkout. The most recent news item in the README dates from 2024.10.1, while the last push to the repository happened on 2026-05-28; the repository is not archived. Release spacing has been several months apart: v2.8.0, v2.8.1 and v2.9.0 span November 2024 to March 2026. Teams planning to depend on it should pin to a release tag rather than track a moving branch. The tree also carries test_tipc/, benchmark/ and a .travis.yml file.

Chinese-first documentation raises the cost for English readers

README.md opens in Simplified Chinese, with the English version in a separate README_en.md. Many of the linked guides carry a _cn suffix: INSTALL_cn.md for installation, QUICK_STARTED_cn.md for a first run, and GETTING_STARTED_cn.md, which walks through building a traffic sign detector in 30 minutes. Data preparation is described in docs/tutorials/data/README.md. The beginner courses for deep learning and object detection are hosted on paddlepaddle.org.cn and Baidu AI Studio. For an English-speaking team this means some tutorial paths require translation, and links copied from the Chinese README will often land on Chinese pages. The demo/ folder offers sample inputs that work regardless of language, including demo/000000014439.jpg, demo/car.jpg, demo/hrnet_demo.jpg and demo/lane00000.jpg, and the project also mentions an online demo where you can run inference on your own images.

Editorial conclusion

PaddleDetection suits teams already committed to PaddlePaddle who want ready-made detectors for pedestrians, vehicles, small objects or rotated boxes, plus a deployment path for them. It is a poor fit for a Python environment that already runs numpy 2 or a recent OpenCV, and for readers who need English-first tutorials. Before adopting it, check the dependency pins against your environment, decide whether you actually want PaddleX instead, and confirm which branch the configs you copy come from.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. PaddlePaddle/PaddleDetection on GitHub
4. README
5. Releases