norfair

library2.3.0pypypi✓ verified 83d ago

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.

ai-ml data

pip install norfair

github ↗package ↗

INSTALL

IMPORT

SIG · NORFAIR

norfair

ai-mlpythonv2.3.0

Install

13.7s avg

Import

2655ms

Disk

338MB

Pass rate

8/ 10

Env Coverage8 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.3.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

glibc

py 3.10

✓ —

✓ 13.2s

py 3.11

✓ —

✓ 12.7s

py 3.12

✓ —

✓ 14.2s

py 3.13

✕ build_error

py 3.9

✓ —

✓ 14.9s

338MB installed

● package 338MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Tracker

✓ from norfair import Tracker

✗ from norfair.tracker import Tracker

Tracker was moved to top-level in v2.0.0. Direct import from submodule may break.

Detection

✓ from norfair import Detection

✗ import norfair.Detection

Detection is a class, not a module.

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}")

Debug

Known issues

breakingIn 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.

affects: <2.0.0

deprecatedPython 3.7 support was dropped in v2.3.0. Python 3.6 was dropped in v2.2.0.

fix

Upgrade to Python >=3.8.

affects: 2.3.0+

gotchaThe 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.

affects: all

gotchaDetection 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).

affects: all

Errors

Common errors & fixes

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

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

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

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)])

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

Using old parameter names from before v1.0.0.

fix

Update to new names: hit_counter_max instead of hit_inertia_max.

Upgrade

Version history

2.3.0latest on PyPI · released Apr 30, 2025

Audit

Dependencies

opencv-pythonrequiredRequired for drawing and video handling.

numpyrequiredCore dependency for array operations.

richoptionalFor console output formatting.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/tryolabs/norfair ↗

packagehttps://pypi.org/project/norfair/ ↗