Norfair

2.3.0 verified Fri May 01 auth: no python

Lightweight Python library for adding real-time multi-object tracking to any detector. Version 2.3.0 supports Python >=3.8,<4.0. Drops Python 3.7. Release cadence is irregular, with major versions every 1-2 years.

pip install norfair

Common errors

error ImportError: cannot import name 'Tracker' from 'norfair' ↓

cause Using an older version of norfair (<2.0.0) where Tracker was in a submodule.

fix

Upgrade to norfair >=2.0.0: pip install --upgrade norfair

error AttributeError: 'Detection' object has no attribute 'points' ↓

cause Detection object was created incorrectly (e.g., passing coordinates as raw list instead of norfair.Point).

fix

Correct construction: Detection(points=[norfair.Point(x, y)])

error TypeError: __init__() got an unexpected keyword argument 'hit_inertia_max' ↓

cause Using old parameter names from before v1.0.0.

fix

Update to new names: hit_counter_max instead of hit_inertia_max.

Warnings

breaking In v2.0.0, the API was significantly simplified: hit_inertia_min removed, hit_inertia_max renamed to hit_counter_max, point_transience renamed to pointwise_hit_counter_max. Old code using these parameters will break. ↓

fix Update parameter names: hit_counter_max (was hit_inertia_max), pointwise_hit_counter_max (was point_transience). Remove hit_inertia_min entirely.

deprecated Python 3.7 support was dropped in v2.3.0. Python 3.6 was dropped in v2.2.0. ↓

fix Upgrade to Python >=3.8.

gotcha The distance_function parameter in Tracker expects a string ('euclidean', 'iou', etc.) or a callable. Using a custom callable that does not accept the correct signature (two arrays of points) will raise an error. ↓

fix Ensure custom distance function signature is: def custom_distance(detection_points: np.ndarray, tracked_points: np.ndarray) -> np.ndarray.

gotcha Detection objects must have a `points` attribute that is a list or numpy array of Point objects. Using raw tuples or lists without converting to norfair.Point may cause attribute errors. ↓

fix Always wrap coordinates with norfair.Point(x, y).

Imports

Tracker
wrong
```
from norfair.tracker import Tracker
```
correct
```
from norfair import Tracker
```
Tracker was moved to top-level in v2.0.0. Direct import from submodule may break.

Detection

wrong

import norfair.Detection

correct

from norfair import Detection

Detection is a class, not a module.

Quickstart

Minimal example using a distance-based tracker with point detections.

import norfair

# Initialize tracker
tracker = norfair.Tracker(distance_function="euclidean", distance_threshold=30)

# Example detection from a detector
detections = [
    norfair.Detection(points=norfair.Point(x=10, y=20)),
    norfair.Detection(points=norfair.Point(x=50, y=60)),
]

# Update tracker with current detections
tracked_objects = tracker.update(detections=detections)

# Print tracked object IDs
for obj in tracked_objects:
    print(f"Tracked ID: {obj.id}")