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.

Examples

Example

CLIPython

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

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

• 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:

boxmot track --detector yolov8n --reid osnet_x0_25_msmt17 --tracker botsort \
  --source video.mp4 --show-trajectories --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)
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.

Outputs

Depending on flags, track can produce:

• annotated videos or rendered frames
• MOT-style text outputs via --save-txt
• cropped detections via --save-crop
• per-run summaries and timing information

See Results and Artifacts.

Detection geometry

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

CLI Arguments

boxmot track

Run tracking only

Usage:

boxmot track [OPTIONS]

Options:

Name	Type	Description	Default
--source	text	file/dir/URL/glob, 0 for webcam	0
--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	video frame-rate	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	CPU threads for image decoding; defaults to min(8, cpu_count)	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	deepocsort, botsort, strongsort, ...	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	choice (none | gsi | gbrc)	Postprocess tracker output: none	gsi (Gaussian smoothed interpolation)
--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
--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