mikel-brostrom/boxmot

Pluggable Python and C++ multi-object tracking modules for axis-aligned and oriented bounding box detections from any model.

---

Docs • Installation • Modes • API Reference • Trackers • Contributing

BoxMOT provides independent detector, segmentor, appearance-encoder, and tracker components built around validated Torch structures. Pipelines compose those components; the CLI owns sources, outputs, materialized datasets, evaluation, tuning, research, and ReID workflows.

• One interface for track, materialize, materialize --time-variant, eval, tune, research, train-reid, eval-reid, compare-reid, export, export-edgetam, install, and native build workflows.
• Swappable components with explicit capabilities and requirements.
• Immutable, keyed Parquet builds with reusable detections, masks, and embeddings.
• Support for both AABB and OBB tracking paths.
• Optional production-ready native C++ tracker implementations with the same metrics as the Python path, opted into via --tracker-backend cpp and embeddable in standalone C++ projects via CMake (see Native C++ Integration).
• A structured Python API for embedding components and pipelines in applications.

BoxMOT supports Python 3.10 through 3.13.

pip install boxmot
boxmot --help

The default package uses the standard PyPI PyTorch build. Source checkouts and CI can explicitly select the lockfile-backed cpu or cu130 profile. For those profiles and mode-specific extras such as yolo, service, evolve, research, onnx, openvino, and tflite, see the installation guide.

Related guides:

• Evaluation and Postprocessing
• Experiment Workflows
• Native C++ Integration

CLI:

boxmot track --detector yolo26n --reid lmbn_n_duke --tracker occluboost \
  --source 0 --save --show

Evaluate a tracker:

boxmot eval \
  --dataset mot17 \
  --split ablation \
  --detector yolox-x-mot17 \
  --reid lmbn-n-duke \
  --tracker botsort

See the evaluation guide for --fps and --calibrate-kf usage.

For saved KITTI predictions, choose the inputs your tracker needs:

boxmot eval --experiment kitti-mots/2d \
  --data-root ./kitti-mots --tracker ocsort --cache-inputs
boxmot eval --experiment kitti-mots/full \
  --data-root ./kitti-mots --tracker eagermot --cache-inputs

Both experiments reference the same kitti-mots.yaml inventory. The first selects 2D boxes; the second adds masks, 3D boxes, calibration, and camera poses. See KITTI experiments.

Use NumPy detections and BGR images directly:

import numpy as np

from boxmot import OccluBoost

tracker = OccluBoost()
dets = np.array([[100, 200, 300, 400, 0.9, 0]])
frame = np.zeros((480, 640, 3), dtype=np.uint8)  # BGR image
tracks = tracker.update(dets, frame)
print(tracks[:, 4].astype(int))  # track IDs

# OBB: (cx, cy, w, h, angle in radians, confidence, class_id)
# tracker = OccluBoost(is_obb=True)
# dets = np.array([[200, 300, 200, 100, np.pi / 6, 0.9, 0]])
# tracks = tracker.update(dets, frame)
# print(tracks[:, 5].astype(int))  # track IDs

Start with CONTRIBUTING.md and the contributor docs.

• Bugs and feature requests: GitHub Issues
• Questions and discussion: GitHub Discussions or Discord
• Limited free consulting is available for nonprofit nature conservation projects using BoxMOT. Contact [email protected] to discuss your project.
• Citation metadata: CITATION.cff
• Commercial support: [email protected]