# Technical Documentation: mikel-brostrom/boxmot

> ℹ️ **Provenance:** Hybrid Fusion: `mikel-brostrom/boxmot` (README + 2 In-Tree Chapters) · [CodeWiki Reference](https://codewiki.google/github.com/mikel-brostrom/boxmot) · Recency: Active (< 180 days)

## 1. Project Overview & Quickstart (mikel-brostrom/boxmot)

BoxMOT gives you one CLI and one Python API for running modern multi-object tracking workflows. It covers direct tracking, cached benchmark evaluation, tuning, research loops, ReID training and evaluation, and ReID export without forcing you to rebuild the detector and tracker stack for each experiment.

## Why BoxMOT

- One interface for `track`, `generate`, `eval`, `tune`, `research`, `train`, `eval-reid`, and `export`.
- Swappable trackers with shared detector and ReID plumbing.
- Benchmark-oriented workflows with reusable detections 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](docs/guides/native-cpp.md)).
- Public Python API for embedding the same workflows in applications and notebooks.

## Installation

BoxMOT supports Python `3.10` through `3.13`.

```bash
pip install boxmot
boxmot --help
```

For mode-specific extras such as `yolo`, `evolve`, `research`, `onnx`, `openvino`, and `tflite`, see the [installation guide](docs/getting-started/installation.md).

## Benchmark Results



Related guides:

- [Evaluation and Postprocessing](docs/guides/evaluation.md)
- [Benchmark Workflows](docs/guides/benchmarks.md)
- [Native C++ Integration](docs/native/index.md)

## Minimal Usage

CLI:

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

Python:

```python
import numpy as np
from boxmot.trackers import OccluBoost

tracker = OccluBoost()

# dets: (N, 6) array with [x1, y1, x2, y2, conf, cls] per detection
dets = np.array([[100, 200, 300, 400, 0.9, 0]], dtype=np.float32)
img = np.zeros((480, 640, 3), dtype=np.uint8)  # current frame

# tracks: (M, 8) array with [x1, y1, x2, y2, id, conf, cls, det_ind] per track
tracks = tracker.update(dets, img)
print(tracks)
```

## Contributing

Start with [CONTRIBUTING.md](CONTRIBUTING.md) and the [contributor docs](docs/contributing/index.md).

## Contributors

<a href="https://github.com/mikel-brostrom/boxmot/graphs/contributors">
  
</a>

## Support and Citation

- Bugs and feature requests: [GitHub Issues](https://github.com/mikel-brostrom/boxmot/issues)
- Questions and discussion: [GitHub Discussions](https://github.com/mikel-brostrom/boxmot/discussions) or [Discord](https://discord.gg/tUmFEcYU4q)
- Citation metadata: [CITATION.cff](https://github.com/mikel-brostrom/boxmot/blob/master/CITATION.cff)
- Commercial support: `box-mot@outlook.com`

## 2. In-Tree Documentation Chapters (mikel-brostrom/boxmot)

## File: README.md

BoxMOT gives you one CLI and one Python API for running modern multi-object tracking workflows. It covers direct tracking, cached benchmark evaluation, tuning, research loops, ReID training and evaluation, and ReID export without forcing you to rebuild the detector and tracker stack for each experiment.

## Why BoxMOT

- One interface for `track`, `generate`, `eval`, `tune`, `research`, `train`, `eval-reid`, and `export`.
- Swappable trackers with shared detector and ReID plumbing.
- Benchmark-oriented workflows with reusable detections 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](docs/guides/native-cpp.md)).
- Public Python API for embedding the same workflows in applications and notebooks.

## Installation

BoxMOT supports Python `3.10` through `3.13`.

```bash
pip install boxmot
boxmot --help
```

For mode-specific extras such as `yolo`, `evolve`, `research`, `onnx`, `openvino`, and `tflite`, see the [installation guide](docs/getting-started/installation.md).

## Benchmark Results



Related guides:

- [Evaluation and Postprocessing](docs/guides/evaluation.md)
- [Benchmark Workflows](docs/guides/benchmarks.md)
- [Native C++ Integration](docs/native/index.md)

## Minimal Usage

CLI:

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

Python:

```python
import numpy as np
from boxmot.trackers import OccluBoost

tracker = OccluBoost()

# dets: (N, 6) array with [x1, y1, x2, y2, conf, cls] per detection
dets = np.array([[100, 200, 300, 400, 0.9, 0]], dtype=np.float32)
img = np.zeros((480, 640, 3), dtype=np.uint8)  # current frame

# tracks: (M, 8) array with [x1, y1, x2, y2, id, conf, cls, det_ind] per track
tracks = tracker.update(dets, img)
print(tracks)
```

## Contributing

Start with [CONTRIBUTING.md](CONTRIBUTING.md) and the [contributor docs](docs/contributing/index.md).

## Contributors

<a href="https://github.com/mikel-brostrom/boxmot/graphs/contributors">
  
</a>

## Support and Citation

- Bugs and feature requests: [GitHub Issues](https://github.com/mikel-brostrom/boxmot/issues)
- Questions and discussion: [GitHub Discussions](https://github.com/mikel-brostrom/boxmot/discussions) or [Discord](https://discord.gg/tUmFEcYU4q)
- Citation metadata: [CITATION.cff](https://github.com/mikel-brostrom/boxmot/blob/master/CITATION.cff)
- Commercial support: `box-mot@outlook.com`

---

## File: docs/index.md

# Quickstart

!!! example "Quickstart"

    === "CLI"

        Install BoxMOT and inspect the CLI:

        ```bash
        pip install boxmot
        boxmot --help
        ```

        Track a video:

        ```bash
        boxmot track --detector yolov8n --reid osnet_x0_25_msmt17 --tracker botsort --source video.mp4 --save
        ```

        Benchmark a tracker on a built-in config:

        ```bash
        boxmot eval --benchmark mot17 --split ablation --tracker boosttrack --verbose
        ```

        Research tracker code changes on a built-in config:

        ```bash
        boxmot research --benchmark mot17 --split ablation --tracker bytetrack --proposal-model openai/gpt-5.4 --max-metric-calls 24
        ```

    === "Python"

        Use the high-level Python API:

        ```python
        from boxmot import BoxMOT

        boxmot = BoxMOT(detector="yolov8n", reid="lmbn_n_duke", tracker="boosttrack")
        run = boxmot.track(source="video.mp4", save=True)
        print(run)

        metrics = boxmot.val(benchmark="mot17-mini")
        print(metrics)
        ```

The high-level Python API is available directly from `boxmot`. Shared CLI and Python defaults still come from `boxmot/configs/modes.yaml` so detector, ReID, tracker, and runtime defaults stay aligned across both entry points.

Next steps:

- [Modes Overview](modes/index.md)
- [CLI Usage](usage/index.md)
- [Python API](python/index.md)
- [Configuration](config/index.md)
- [API Reference](python/index.md)
- [Trackers](trackers/index.md)

--- METRICS ---
- Files Extracted: 3
- Estimated Token Budget: ~1739 tokens
- Recency Window: Active (< 180 days)
- Canonical Reference: https://codewiki.google/github.com/mikel-brostrom/boxmot