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.
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
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.
Benchmark Results
Related guides:
Minimal Usage
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.
Track Attributes with Ollama and vLLM
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.
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
