tracktors

Trackers, after the coordinates discovered tensors.

Tracktors is Roboflow's private, tensor-native fork of Trackers, scoped to the four tracker paths used by Inference: SORT, ByteTrack, OC-SORT, and BoT-SORT. It consumes SuperiorVision's tensor-native supervision.Detections without making the boxes take a ceremonial trip through NumPy first.

Both from tracktors import ... and the legacy from trackers import ... interface are supported while Inference migrates. Same API, same algorithms, fewer surprise CPU field trips.

Turning a GPU tensor into NumPy so a Kalman filter can immediately rebuild the same numbers somewhere else is not object tracking. It is luggage handling. Tracktors is retiring the carousel.

Why Tracktors?

• Clean-room implementations. Every algorithm is re-implemented from the original paper — not a thin wrapper around someone else's code. You can read it, understand it, and modify it.
• Detector-agnostic. Works with YOLO, DETR, RT-DETR, or any model that produces bounding boxes. No inference library required or assumed.
• SuperiorVision tensor native. Pass tensor-backed sv.Detections in and get tensor-backed tracked detections back on the same device—zero glue code and zero NumPy exit tax.
• Benchmarked across four datasets. MOT17, SportsMOT, SoccerNet, and DanceTrack — at default parameters and after hyperparameter tuning, so you know what to expect before you deploy.
• Tunable out of the box. Built-in Optuna-based hyperparameter search via tracktors tune (or the compatible trackers tune) so you can optimize for your specific scene and detector.
• Camera motion compensation. BoT-SORT handles moving cameras natively, keeping track IDs stable even when the whole frame shifts.

Install

pip install tracktors

git clone git@github.com:roboflow/tracktors.git
cd tracktors
uv sync

The package is published on PyPI; the source repository remains private.

Quick Start

Add tracking to your existing detection pipeline in a few lines. Every tracker shares the same update(detections, frame=None) interface, so switching algorithms later is a one-line change. The example below uses inference as the detector — swap it for any detector that returns supervision.Detections.

import cv2
import supervision as sv
from inference import get_model
from tracktors import ByteTrackTracker

model = get_model(model_id="rfdetr-medium")
tracker = ByteTrackTracker()

cap = cv2.VideoCapture("video.mp4")
while cap.isOpened():
    ret, frame = cap.read()
    if not ret:
        break

    result = model.infer(frame)[0]
    detections = sv.Detections.from_inference(result)
    tracked = tracker.update(detections)

For more examples, see the tracking guide.

Track from CLI

Prefer the terminal? Point tracktors track at a video, webcam feed, RTSP stream, or image directory and it handles detection, tracking, and annotated output in one command — no Python script required.

tracktors track \
    --source video.mp4 \
    --output output.mp4 \
    --model rfdetr-medium \
    --tracker bytetrack \
    --show-labels \
    --show-trajectories

For all CLI options, see the tracking guide.

Algorithms

Each tracker below is a faithful implementation of its original paper. Pick the one that fits your scene, or run the benchmark to find out which performs best on your data.

All scores use default parameters on the standard split. See the tracker comparison for tuned numbers and methodology.

trackers also ships McByte, a mask-conditioned tracker that extends BoT-SORT-style association with temporally propagated SAM/Cutie segmentation masks as an extra matching cue. It requires optional heavyweight dependencies (torch, SAM, Cutie) not installed by default — see the McByte docs for setup and benchmark numbers.

Evaluate

Once you have tracking results, you want to know how good they are. trackers eval computes CLEAR, HOTA, and Identity metrics against ground-truth annotations and prints a per-sequence breakdown alongside the combined score.

tracktors eval \
    --gt-dir ./data/mot17/val \
    --tracker-dir results \
    --metrics CLEAR HOTA Identity \
    --columns MOTA HOTA IDF1

Sequence                        MOTA    HOTA    IDF1
----------------------------------------------------
MOT17-02-FRCNN                30.192  35.475  38.515
MOT17-04-FRCNN                48.912  55.096  61.854
MOT17-05-FRCNN                52.755  45.515  55.705
MOT17-09-FRCNN                51.441  50.108  57.038
MOT17-10-FRCNN                51.832  49.648  55.797
MOT17-11-FRCNN                55.501  49.401  55.061
MOT17-13-FRCNN                60.488  58.651  69.884
----------------------------------------------------
COMBINED                      47.406  50.355  56.600

For the full evaluation workflow, see the evaluation guide.

Download Datasets

Need benchmark data to evaluate against? trackers download pulls MOT17, SportsMOT, and other supported datasets with a single command, handling splits and assets selectively so you only download what you need.

tracktors download mot17 \
    --split val \
    --asset annotations,detections

For more download options, see the download guide.

Try It

Want to see it in action before writing any code? Try trackers in your browser with our Hugging Face Playground — no install required.

Where to go next

• New to tracking? Start with the tracking guide — it walks through the Python API and CLI end to end.
• Want benchmarks? The tracker comparison covers all four algorithms across all four datasets, at default and tuned parameters, with guidance on which to pick for your scene.
• Building a research pipeline? The evaluation guide and download guide cover the full offline benchmarking workflow.
• Upstream API reference → trackers.roboflow.com
• Try without installing → Hugging Face Playground
• Questions? Find us on Discord.

Contributing

We welcome contributions. Read our contributor guidelines to get started.

License

The code is released under the Apache 2.0 license.