Tracking you bolt onto any detector
Norfair is a lightweight library that adds multi-object tracking to a detector you already have. You bring per-frame detections from any model (YOLO, a custom network, anything), and Norfair maintains consistent IDs across frames using a Kalman filter plus a distance function you can customize. The design choice that defines it is being detector-agnostic: it does not ship its own detector or bind to one architecture, so it drops into an existing pipeline. At 2,653 stars as of 2026-06, it is a small but well-regarded option when you want tracking without adopting a heavier framework.
It is built on numpy at its core, which keeps it light and easy to add.
What it does
You feed Norfair a list of detections each frame as points or boxes, and it returns tracked objects with stable IDs. The matching uses a Kalman filter to predict motion and a distance function (IoU, Euclidean, or your own) to associate detections to tracks. Beyond the basics it supports camera-motion estimation for moving cameras and optional re-identification with an external embedding model for recovering IDs after occlusion. It tracks not just boxes but arbitrary points, so pose keypoints work too.
Install
pip install norfair
# with video helpers and metrics
pip install "norfair[video,metrics]"The core install is minimal. The video and metrics extras add OpenCV helpers and MOT evaluation, useful for prototyping and benchmarking.
Tuning the tracker
The thing you will actually spend time on is parameters, and the most common complaint is ID switches: a tracked object getting a new ID after a gap, or two objects swapping IDs when they cross. The levers are the maximum association distance, the hit-counter and initialization-delay settings, and the Kalman process noise. There is no universal setting; the right values depend on your video’s resolution, object speed, and detection rate. Budget time to tune these for your scene, and accept that during a genuine collision, a Kalman-plus-distance tracker can swap IDs as a fundamental limitation, which re-id helps but does not fully solve.
Where it fits, and where it doesn’t
Norfair is a good fit when you want to add tracking to a detector you already trust, when you need a detector-agnostic and customizable tracker, or when camera motion or arbitrary-point tracking (like pose) are in scope. Its small dependency footprint makes it easy to slot in.
Where it asks more of you: tuning is on you, the advanced features (camera motion, re-id) are powerful but under-documented and take effort to set up, and ID switches during collisions are an algorithmic limit, not a bug to configure away. Note also that the last release was v2.3.0 in early 2025, so development has been quiet recently; it is stable and not abandoned, but check current activity if you need ongoing fixes.
norfair versus the alternatives
| Norfair | ByteTrack | DeepSORT | supervision | |
|---|---|---|---|---|
| Approach | detector-agnostic, customizable | YOLO-centric algorithm | re-id centric | CV utility toolkit |
| Core | Kalman plus custom distance | byte-level association | Kalman plus deep re-id | includes tracking helpers |
| Weight | very light (numpy) | light | heavier (CNN re-id) | light |
| Best for | flexible, custom pipelines | real-time YOLO workflows | heavy-occlusion re-id | detection post-processing |
Stars where shown are from GitHub as of June 2026. ByteTrack and DeepSORT are specific algorithms rather than detector-agnostic frameworks; ByteTrack suits YOLO-first real-time work, DeepSORT prioritizes re-identification. supervision is a broader CV toolkit that includes tracking helpers and pairs well with detectors. Norfair’s niche is the flexible, lightweight, detector-agnostic tracker you customize.
The star curve
The star curve reflects a focused utility that grew steadily among CV developers who needed tracking without a heavy framework, rather than a viral spike. The flattening recently tracks the quieter release cadence.
What the issue tracker warns you about
The recurring questions are about tuning and integration, and tellingly few carry strong reactions, which suggests broad but unsettled pain rather than one big bug. ID switches and distance-threshold tuning dominate, with no community consensus on best settings because they are scene-dependent. Integrating with specific detectors needs format conversion that trips people up. Camera-motion compensation and re-id are powerful but the docs are thin, so setup is involved. And ID swaps during true collisions are a known algorithmic limit. None of this is a defect; it is the nature of a configurable tracker.
Related
For a broader CV toolkit with tracking helpers, see supervision. For dataset curation and evaluation, see fiftyone. For OCR on document images, see PaddleOCR. For what is trending, see the daily digest and the weekly report.
FAQ
Is Norfair still maintained? The last release was v2.3.0 in early 2025, and development has been quiet since. It is stable and not abandoned, but if you need ongoing fixes or new features, check current commit activity before depending on it.
Norfair vs ByteTrack vs supervision, which should I use? Norfair is a detector-agnostic, customizable tracker. ByteTrack is a specific algorithm suited to YOLO-first real-time work. supervision is a broader CV toolkit that includes tracking helpers. Choose Norfair for a flexible, lightweight tracker you tune yourself.
How do I add Norfair to a YOLO pipeline? Run your detector each frame, convert its outputs into Norfair Detection objects (points or boxes), pass them to the Tracker, and read back tracked objects with IDs. The main work is mapping your detector’s output format to Norfair’s input.
Why do tracked IDs keep switching? ID switches come from association failing across gaps or during crossings. Tune the maximum association distance, hit-counter, initialization delay, and Kalman noise for your scene. During a genuine collision, ID swaps are an algorithmic limit that re-id can mitigate but not fully prevent.
Can Norfair handle a moving camera? Yes, with its camera-motion estimation, which compensates for camera movement using homography. It works but the documentation is thin and it needs sufficient feature points, so expect some setup effort.