Track

Use track when you want end-to-end detector + tracker execution on a real source such as a webcam, video file, image directory, or stream. You can also select a configured dataset and split; BoxMOT then resolves the dataset source while keeping the detector and ReID models you selected.

Examples

Example

CLIPython

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

Track a configured dataset split with explicitly selected models:

boxmot track \
  --detector yolo26n \
  --reid lmbn_n_duke \
  --tracker occluboost \
  --dataset mot17 \
  --split ablation \
  --save \
  --show

from boxmot import BoxMOT

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

Common source values

Pass either --source or --dataset, not both. Omitting both retains the default webcam source (0). --split selects a configured dataset split and defaults to the split declared by the dataset profile.

• 0 for a webcam
• video.mp4 for a local video
• path/to/images for an image directory
• path/*.jpg for a glob
• rtsp://... or http://... for a network stream
• YouTube URLs for supported detector backends

Typical patterns

Example

CLIPython

Track with trajectories and Kalman-filter predictions during missed detections:

boxmot track --detector yolov8n --reid osnet_x0_25_msmt17 --tracker botsort \
  --source video.mp4 --show-trajectories --show-kf-preds --save

Track selected classes only:

boxmot track --detector yolov8s --tracker bytetrack --source 0 --classes 16,17

Track each class independently:

boxmot track --detector yolov8n --tracker bytetrack --source video.mp4 --per-class --save

from boxmot import BoxMOT

boxmot = BoxMOT(detector="yolov8n", reid="osnet_x0_25_msmt17", tracker="botsort")
saved = boxmot.track(
    source="video.mp4",
    save=True,
    save_txt=True,
    show_trajectories=True,
    show_kf_preds=True,
)
print(saved.video_path)
print(saved.text_path)

filtered = BoxMOT(detector="yolov8s", tracker="bytetrack", classes=[16, 17])
webcam_run = filtered.track(source=0, verbose=False)
print(webcam_run.summary)

Class filtering in Python is configured on BoxMOT(...) via classes=[...], not passed to track(...) directly.

Startup and CPU performance

The final tracking summary reports startup costs for detector loading, tracker/ReID loading, output preparation, and first-frame acquisition separately from per-frame inference. A first run can also download missing weights or populate dependency caches; those one-time costs should disappear on later runs.

When tracking people only, filter the detector before ReID so unrelated COCO objects do not become extra embedding crops:

boxmot track \
  --detector yolo26n \
  --reid lmbn_n_duke.onnx \
  --tracker occluboost \
  --source 0 \
  --classes 0 \
  --fps 30 \
  --save \
  --show

The ONNX ReID artifact is often faster than the PyTorch artifact on CPU. On Apple Silicon, keep the PyTorch artifact and try --device mps instead. The --fps option controls saved-video playback rate; live sources otherwise use a 30 FPS fallback without opening the camera a second time just to query it.

If every fresh process says that Matplotlib is rebuilding its font cache, make MPLCONFIGDIR point to a persistent writable directory. An unwritable or temporary font cache can add many seconds before the detector is ready.

Outputs

Depending on flags, track can produce:

• annotated videos or rendered frames
• MOT-style text outputs via --save-txt
• cropped detections via --save-crop
• a structured TrackRunResult from the Python API (see High-level API)

Native C++ tracking

Use --tracker-backend cpp when you want the in-process native C++ tracker implementation instead of the Python implementation:

boxmot track --detector yolov8n --tracker bytetrack --tracker-backend cpp --source video.mp4
boxmot track --detector yolov8n --reid osnet_x0_25_msmt17 --tracker botsort --tracker-backend cpp --source 0

Native live tracking is currently registered for botsort, bytetrack, ocsort, occluboost, and sfsort. See Native C++ Integration for build requirements and embedding details.

Native live trackers do not yet provide class-separated state, so --per-class requires the Python tracker backend.

Detection geometry

track accepts either AABB or OBB detections, and BoxMOT switches automatically based on tensor shape. See Concepts.

CLI Arguments

boxmot track

Run tracking only

Usage:

boxmot track [OPTIONS]

Options:

Name	Type	Description	Default
--dataset	text	dataset id or YAML file, e.g. mot17 or boxmot/configs/datasets/mot17.yaml; uses the selected/default detector and ReID model	None
--source	text	file/dir/URL/glob, 0 for webcam	0
--split	text	Dataset split to use (e.g. train, val, test, ablation). Overrides auto-detection from source path.	None
--tracker-backend	choice (python | cpp)	Tracker implementation backend. Native 'cpp' is available for botsort, bytetrack, occluboost, ocsort, and sfsort.	python
--imgsz	text	Image size for model input as H,W (e.g. 800,1440) or single int for square. Default: read from the selected detector config, otherwise use detector-specific defaults.	None
--fps	integer range (1 and above)	frame-rate override: saved track video FPS or evaluation target FPS	None
--conf	float	Min confidence threshold. Default: read from the selected detector config, fallback 0.01.	None
--iou	float	IoU threshold for NMS	0.7
--device	text	cuda device(s), e.g. 0 or 0,1,2,3 or cpu	cpu
--batch-size	integer	micro-batch size for batched detection/embedding	16
--auto-batch / --no-auto-batch	boolean	probe GPU memory with a dummy pass to pick a safe batch size	True
--resume / --no-resume	boolean	resume detection/embedding generation from progress checkpoints	True
--n-threads	integer range (1 and above)	Maximum CPU worker budget for image decoding and cached tracking	4
--project	Path	save results to project/name	runs
--name	text	save results to project/name	exp
--exist-ok	boolean	existing project/name ok, do not increment	False
--half	boolean	use FP16 half-precision inference	False
--vid-stride	integer	video frame-rate stride	1
--ci	boolean	reuse existing runs in CI (no UI)	False
--tracker	text	one of: strongsort, ocsort, bytetrack, sfsort, botsort, deepocsort, hybridsort, boosttrack, occluboost, sam2mot	bytetrack
--verbose	boolean	print detailed logs	False
--show-timing / --hide-timing	boolean	print runtime timing summary after evaluation	False
--agnostic-nms	boolean	class-agnostic NMS	False
--postprocessing	text	Postprocess tracker output (comma-separated, applied in order): none	gsi
--show	boolean	display tracking in a window	False
--show-labels / --hide-labels	boolean	show or hide detection labels	True
--show-conf / --hide-conf	boolean	show or hide detection confidences	True
--show-trajectories	boolean	overlay past trajectories	False
--show-kf-preds	boolean	show Kalman-filter predictions	False
--save-txt	boolean	save results to a .txt file	False
--save-crop	boolean	save cropped detections	False
--save	boolean	save annotated video	False
--line-width	integer	bounding box line width	None
--per-class	boolean	track each class separately	False
--target-id	integer	ID to highlight in green	None
--masks-dir	text	Override directory for cached segmentation masks (.npz files)	None
--masks-model	choice (maskrcnn)	Mask model to use for generation (stored under cache tree automatically)	None
--detector	Path	path to YOLO weights for detection	/home/runner/work/boxmot/boxmot/models/yolov8n.pt
--reid	Path	path to ReID model weights	/home/runner/work/boxmot/boxmot/models/osnet_x0_25_msmt17.pt
--classes	text	filter by class indices, e.g. 0 or "0,1"	None
--help	boolean	Show this message and exit.	False