{"id":24118,"library":"norfair","title":"Norfair","description":"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.","status":"active","version":"2.3.0","language":"python","source_language":"en","source_url":"https://github.com/tryolabs/norfair","tags":["multi-object-tracking","real-time","computer-vision","object-tracking"],"install":[{"cmd":"pip install norfair","lang":"bash","label":"Install from PyPI"}],"dependencies":[{"reason":"Required for drawing and video handling.","package":"opencv-python","optional":false},{"reason":"Core dependency for array operations.","package":"numpy","optional":false},{"reason":"For console output formatting.","package":"rich","optional":true}],"imports":[{"note":"Tracker was moved to top-level in v2.0.0. Direct import from submodule may break.","wrong":"from norfair.tracker import Tracker","symbol":"Tracker","correct":"from norfair import Tracker"},{"note":"Detection is a class, not a module.","wrong":"import norfair.Detection","symbol":"Detection","correct":"from norfair import Detection"}],"quickstart":{"code":"import norfair\n\n# Initialize tracker\ntracker = norfair.Tracker(distance_function=\"euclidean\", distance_threshold=30)\n\n# Example detection from a detector\ndetections = [\n    norfair.Detection(points=norfair.Point(x=10, y=20)),\n    norfair.Detection(points=norfair.Point(x=50, y=60)),\n]\n\n# Update tracker with current detections\ntracked_objects = tracker.update(detections=detections)\n\n# Print tracked object IDs\nfor obj in tracked_objects:\n    print(f\"Tracked ID: {obj.id}\")","lang":"python","description":"Minimal example using a distance-based tracker with point detections."},"warnings":[{"fix":"Update parameter names: hit_counter_max (was hit_inertia_max), pointwise_hit_counter_max (was point_transience). Remove hit_inertia_min entirely.","message":"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.","severity":"breaking","affected_versions":"<2.0.0"},{"fix":"Upgrade to Python >=3.8.","message":"Python 3.7 support was dropped in v2.3.0. Python 3.6 was dropped in v2.2.0.","severity":"deprecated","affected_versions":"2.3.0+"},{"fix":"Ensure custom distance function signature is: def custom_distance(detection_points: np.ndarray, tracked_points: np.ndarray) -> np.ndarray.","message":"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.","severity":"gotcha","affected_versions":"all"},{"fix":"Always wrap coordinates with norfair.Point(x, y).","message":"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.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Upgrade to norfair >=2.0.0: pip install --upgrade norfair","cause":"Using an older version of norfair (<2.0.0) where Tracker was in a submodule.","error":"ImportError: cannot import name 'Tracker' from 'norfair'"},{"fix":"Correct construction: Detection(points=[norfair.Point(x, y)])","cause":"Detection object was created incorrectly (e.g., passing coordinates as raw list instead of norfair.Point).","error":"AttributeError: 'Detection' object has no attribute 'points'"},{"fix":"Update to new names: hit_counter_max instead of hit_inertia_max.","cause":"Using old parameter names from before v1.0.0.","error":"TypeError: __init__() got an unexpected keyword argument 'hit_inertia_max'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}