boxmot

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.

Why BoxMOT

• One interface for track, materialize, materialize --time-variant, eval, tune, research, train-reid, eval-reid, compare-reid, export, 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 native C++ tracker implementations selected with --tracker-backend cpp, with shared detection/output contracts and documented backend differences. They are also embeddable in standalone C++ projects through CMake (see Native C++ Integration and platform dependency installation).
• A structured Python API for embedding components and pipelines in applications.

Installation

BoxMOT supports Python 3.10 through 3.13.

pip install boxmot "ultralytics>=8.4.58"
boxmot --help

This installs BoxMOT and the Ultralytics detector backend used below. For tracking existing detections through the Python API, pip install boxmot is enough. See Installation for optional workflows and PyTorch and source setup for CPU/CUDA profiles and YOLOX.

Benchmark Results

Related guides:

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

Minimal Usage

The mode guides provide toggleable CLI and Python examples for tracking, materialization, evaluation, tuning, research, ReID training, and export. Python workflow functions accept settings directly as keyword arguments.

Select a command, detector, ReID model, tracker, and other settings interactively:

boxmot ui

The terminal UI previews the command before you run it and enables an interactive dashboard for workflows that report live progress.

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

Python trackers except SFSORT, plus native ByteTrack, BotSort, OcSort, and OccluBoost, support opt-in capture timing with --variable-dt or KalmanConfig(variable_dt=True). The Python API requires a timestamp on every update. SFSORT uses fixed steps on both backends. See elapsed-time tracking.

Python with axis-aligned boxes (AABB):

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

Python with oriented boxes (OBB):

import numpy as np

from boxmot import OccluBoost

tracker = OccluBoost(is_obb=True)
# cx, cy, width, height, angle in radians, confidence, class_id
dets = np.array([[200, 300, 200, 100, np.pi / 6, 0.9, 0]])
frame = np.zeros((480, 640, 3), dtype=np.uint8)  # BGR image
tracks = tracker.update(dets, frame)
print(tracks[:, 5].astype(int))  # track IDs

2D/3D sensor fusion with ego-motion compensation using EagerMot:

import numpy as np
import torch

from boxmot import EagerMot
from boxmot.structures import CameraModel

tracker = EagerMot()
projection = torch.tensor([  # synthetic camera projection
    [100, 0, 100, 0],
    [0, 100, 50, 0],
    [0, 0, 1, 0],
], dtype=torch.float32)
camera_to_world = torch.eye(4, dtype=torch.float32)
camera_to_world[0, 3] = 1.0  # synthetic pose: camera at world x = 1 meter
camera = CameraModel(
    projection=projection,
    image_size=(100, 200),  # height, width
    camera_to_world=camera_to_world,
)
dets = np.array([[78, 39, 122, 62, 0.95, 0]])
# 3D in camera coordinates: x, y, z, yaw, length, width, height, confidence, class_id
dets_3d = np.array([[0, 1, 10, 0, 4, 2, 2, 0.9, 0]])

tracks_2d, tracks_3d = tracker.update(
    dets,
    detections_3d=dets_3d,
    camera=camera,
)
print(tracks_2d[:, 4].astype(int))  # image track IDs
print(tracks_3d[:, 7].astype(int))  # 3D track IDs

Replace the synthetic pose with the current frame’s absolute 4×4 camera-to-world transform on every update. KITTI evaluation loads these from poses.npy when the dataset declares a poses modality. If poses are unavailable, omit CameraModel.camera_to_world throughout the sequence to track in camera coordinates. A NumPy camera projection can also be passed with a frame that provides its image dimensions; use CameraModel when no frame is supplied.

License

BoxMOT is licensed under the GNU Affero General Public License v3 (AGPL-3.0).

Each detector and segmentor integrated with BoxMOT retains its own upstream license. See the respective project’s license for its terms. Other third-party components also retain their respective licenses and notices.

Contributing

Start with CONTRIBUTING.md and the contributor docs.

Contributors

Support and Citation

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