open-mmlab/mmdetection · error · RuntimeError

motmetrics is not installed, please install

Error message

motmetrics is not installed,                 please install it by: pip install motmetrics

What it means

SORTTracker uses motmetrics (py-motmetrics) for its utils/association path; if the package failed to import at module load, constructing SORT raises RuntimeError before any tracking happens.

Source

Thrown at mmdet/models/trackers/sort_tracker.py:58

        match_iou_thr (float, optional): Threshold of the IoU matching process.
            Defaults to 0.7.
        num_tentatives (int, optional): Number of continuous frames to confirm
            a track. Defaults to 3.
    """

    def __init__(self,
                 motion: Optional[dict] = None,
                 obj_score_thr: float = 0.3,
                 reid: dict = dict(
                     num_samples=10,
                     img_scale=(256, 128),
                     img_norm_cfg=None,
                     match_score_thr=2.0),
                 match_iou_thr: float = 0.7,
                 num_tentatives: int = 3,
                 **kwargs):
        if motmetrics is None:
            raise RuntimeError('motmetrics is not installed,\
                 please install it by: pip install motmetrics')
        super().__init__(**kwargs)
        if motion is not None:
            self.motion = TASK_UTILS.build(motion)
            assert self.motion is not None, 'SORT/Deep SORT need KalmanFilter'
        self.obj_score_thr = obj_score_thr
        self.reid = reid
        self.match_iou_thr = match_iou_thr
        self.num_tentatives = num_tentatives

    @property
    def confirmed_ids(self) -> List:
        """Confirmed ids in the tracker."""
        ids = [id for id, track in self.tracks.items() if not track.tentative]
        return ids

    def init_track(self, id: int, obj: Tuple[Tensor]) -> None:
        """Initialize a track."""

View on GitHub (pinned to cfd5d3a985)

Solutions

pip install motmetrics
Verify import in the active env: python -c 'import motmetrics'
Also ensure lap and scipy are present since SORT trackers need them too

Example fix

# before: RuntimeError: motmetrics is not installed
# after
pip install motmetrics

Defensive patterns

Strategy: validation

Validate before calling

import importlib.util
assert importlib.util.find_spec('motmetrics'), 'pip install motmetrics'

Try / catch

try:
    tracker = SORTTracker(...)
except RuntimeError as e:
    if 'motmetrics' in str(e):
        raise SystemExit('Missing dependency: pip install motmetrics')
    raise

Prevention

Install motmetrics alongside lap and scipy for MOT work
Keep tracking configs in envs with the full extras installed

When it happens

Trigger: tracker=dict(type='SORTTracker') or DeepSORTTracker construction without motmetrics installed.

Common situations: Running MOT tracking configs (sort, deepsort) after a base install; motmetrics is an optional runtime extra of mmdet.

Related errors

AI-assisted analysis of open-mmlab/mmdetection@cfd5d3a985 (2026-08-27). Data as JSON: /api/errors/dc8a61ef0aea2978. Report an issue: GitHub.