---
id: norfair
version: "2.3.0"
license: BSD-3-Clause
license_treatment: permissive
maintenance: aging
---

# norfair — Lightweight Python library for adding real-time multi-object tracking to any detector.

License: permissive · Maintenance: aging · Downloads: 123.4K/mo

## What it is and what it does

Norfair is a Python library that integrates tracking into video processing pipelines by taking detections (expressed as coordinate sets) from any object or keypoint detector and assigning consistent identities across frames. It uses Kalman filtering to predict object positions and matches predictions to new detections via customizable distance functions, enabling you to track centroids, bounding boxes, human keypoints, or 3D points with minimal code changes.

The library is designed for modularity and speed: it plugs into existing detection workflows (YOLO, Detectron2, OpenPose, etc.) and supports advanced scenarios including moving cameras, appearance-based re-identification, and n-dimensional tracking. It depends on numpy, scipy, and filterpy for numerical computation, and rich for terminal output, making it lightweight enough for embedded systems when optional video and metrics features are not needed.

Use it for:

- Track vehicle or pedestrian centroids in traffic monitoring or surveillance video with a YOLO or Detectron2 detector.
- Track human body keypoints across video frames for pose-based analytics or sports performance analysis.
- Maintain object identity in scenes with camera motion by estimating and compensating for pan, tilt, rotation, and zoom.
- Re-identify occluded or briefly lost objects using appearance embeddings to improve tracking robustness in crowded scenes.
- Track 3D points from depth sensors or multi-view systems for robotics or 3D reconstruction workflows.
- Integrate tracking into a custom video inference loop without external frameworks, using only Norfair and a detector.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Norfair adds real-time multi-object tracking to any detector by matching detected coordinates across frames using configurable distance functions and Kalman filtering.

Yes, with conditions. Norfair is production-stable and well-maintained for its core use case: adding tracking to any detector with minimal code. Install it if you need real-time multi-object tracking in video and already have a detector. The low install friction and permissive license make adoption straightforward. However, the aging maintenance status (471 days since last release) means you should verify that its Kalman filter and distance-matching approach fit your specific tracking problem before committing to it in a new project.

## Install

pip install norfair
uv add norfair
poetry add norfair

## Installing norfair

Before you install: Low friction: pure Python wheel with five runtime dependencies (numpy, scipy, filterpy, rich, importlib-metadata). Status is aging—last release 471 days ago—but the repository remains active with recent commits and no archived flag.

License in practice: BSD-3-Clause is permissive; you can use, modify, and distribute Norfair with minimal restrictions, provided you include the license notice.

Quickstart:

pip install norfair

from norfair import Tracker
tracker = Tracker(distance_function=your_distance_fn)
tracked_objects = tracker.update(detections=new_detections)

Requires Python 3.8 or later. Optional features (video helpers, MOT metrics) need additional dependencies installable via norfair[video] or norfair[metrics].

Verify before relying:

- Actual performance characteristics (latency, throughput) on typical video resolutions and frame rates.
- Maturity of re-identification and camera-motion features relative to production use.
- Community adoption and real-world deployment feedback beyond the 2,675 GitHub stars.

## Package facts

- License: BSD-3-Clause (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: aging
- Downloads: 123.4K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

multi-object tracking library, real-time object tracking, kalman filter tracking, video object tracking, pose tracking keypoints, re-identification tracking, moving camera tracking, video-tracking, kalman-filter, multi-object-tracking

[View on SkillFed](https://skillfed.io/packages/norfair) · [View on PyPI](https://pypi.org/project/norfair/)