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 • Datasets • 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, 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.

Requires Python 3.10–3.13.

Install from PyPI:

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

Or, from a source checkout, run in the repository root:

pip install "uv==0.12.4"
uv sync --extra cpu --extra yolo
uv run --no-sync python -m boxmot.engine.cli --help

Replace --extra cpu with --extra cu130 for CUDA 13.0.

See installation options, source and CPU/CUDA setup, and GPU batch sizing.

Related guides:

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

Choose a workflow and settings with the terminal UI:

boxmot ui

Track a webcam from the CLI:

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

Python with axis-aligned boxes (AABB):

import numpy as np

from boxmot import OccluBoost

tracker = OccluBoost()
# x1, y1, x2, y2, confidence, class_id
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

See the mode guides for more CLI and Python workflows. Advanced examples: capture timing, prompted tracking with EdgeTAM, and 2D/3D fusion with EagerMot.

Provider	Description	Pros	Cons
	Easily run vision models locally, with straightforward installation, model downloads, and API access.	Simple setup; images stay on your machine when using local models.	Large models need substantial RAM/VRAM and disk space; speed depends on your hardware.
	Serve vision-language models on your own infrastructure, with more configuration options for handling many requests efficiently.	Efficient batching for concurrent requests; control over models and infrastructure.	More setup, tuning, and maintenance; you provide the hardware to run the models.

Add clothing, footwear, and pose descriptions to person tracks with Ollama or vLLM. Display attributes alongside track IDs and export structured JSON results. Every attribute run requires PostgreSQL for its queue and retained results; the Compose workflow starts the database automatically.

See the Track Attributes guide for setup, configuration, and examples. To run detection, ReID, and the VLM on NVIDIA GPUs, use the GPU Compose setup.

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.

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 box-mot@outlook.com to discuss your project.
• Citation metadata: CITATION.cff
• Commercial support: box-mot@outlook.com