CLI Migration Guide

The CLI now groups track options by responsibility. The new dotted arguments map directly to the option dataclasses used by track, and are also available in YAML configuration files.

Semantic legacy spellings remain available during the transition. Each use emits a FutureWarning with the replacement. Do not combine a legacy argument and its replacement in one command; the CLI rejects that ambiguity. Develop's --no-boxes and --no-ids still work and map to --show.no_boxes and --show.no_ids. Each warning names the release that removes it: 2.10.0.

Track command

Use dotted paths for grouped detection, filtering, output, visualization, and tracker options. --display remains ungrouped.

trackers track \
    --source source.mp4 \
    --detection.model rfdetr-base \
    --detection.confidence 0.3 \
    --filters.classes [person,car] \
    --tracker sort \
    --tracker.lost_track_buffer 40 \
    --output.video tracked.mp4 \
    --show.no_boxes

Every boolean option is a pair: --show.boxes turns it on, --show.no_boxes turns it off, and --show.boxes false or --show.boxes=false spell the same thing explicitly. The negation sits on the field rather than the group, so it stays readable for any group name — --detection.no_fast, never --no_detection.fast. Repeating both halves is allowed; the last one wins. A --config file keeps one plain boolean key per field, and a command-line flag always overrides it.

This covers ungrouped options too — --display / --no_display, --no_enqueue_defaults on tune, --no_list_available on download.

The algorithm and its parameters share one group, mirroring --detection.model and the rest of the detection options. --tracker sort is shorthand for --tracker.name sort; both spellings are supported and neither warns.

Tracker parameters are the exception: they default to None, meaning "leave the tracker's own default alone", so they take an explicit value and have no negative half. Develop's bare --tracker.enable_cmc flag turned camera motion compensation off, since the parameter itself defaults to True, so the bare spelling still maps to --tracker.enable_cmc=false and warns. Prefer --tracker.enable_cmc true or --tracker.enable_cmc false; they say what they do. The same applies to --tracker.instant_first_frame_activation.

As in develop, specify either a model or a precomputed MOT file, not both.

Legacy argument	Current argument
--model	--detection.model
--detections	--detection.mot_file
--model.confidence	--detection.confidence
--model.device	--detection.device
--model.api_key	--detection.api_key
--classes	--filters.classes
--track_ids	--filters.track_ids
--tracker	--tracker (unchanged)
--tracker.<name>	--tracker.<name>
-o, --output	--output.video
--mot-output	--output.mot_results
--overwrite	--output.overwrite
--display	--display (unchanged)
--show-boxes	--show.boxes
--no-boxes	--show.no_boxes
--no-show.boxes	Removed; use --show.no_boxes
--show-masks	--show.masks
--show-labels	--show.labels
--show-ids	--show.ids
--no-ids	--show.no_ids
--no-show.ids	Removed; use --show.no_ids
--show-confidence	--show.confidence
--show-trajectories	--show.trajectories

List-valued filters

--filters.classes and --filters.track_ids take lists, matching the list-valued --metrics and --columns options of eval and tune. Bracket shorthand needs no quoting, so --filters.classes [person,car], --filters.classes [0,2], and the mixed --filters.classes [person,2] all work. Comma-separated strings remain available as a warning-emitting alias.

Legacy value form	Current value form
--filters.classes person,car	--filters.classes [person,car]
--filters.track_ids 1,3,5	--filters.track_ids [1,3,5]

Abbreviated tracker parameters

Tracker parameter names abbreviate their standard leading token on the command line: minimum_ becomes min_ and maximum_ becomes max_. Domain words such as threshold stay spelled out. Every develop parameter path whose spelling did not change keeps working as-is, without a warning; the unabbreviated paths remain as warning-emitting aliases.

Legacy argument	Current argument
--tracker.minimum_consecutive_frames	--tracker.min_consecutive_frames
--tracker.minimum_iou_threshold	--tracker.min_iou_threshold
--tracker.minimum_iou_threshold_first_assoc	--tracker.min_iou_threshold_first_assoc
--tracker.minimum_iou_threshold_second_assoc	--tracker.min_iou_threshold_second_assoc
--tracker.minimum_iou_threshold_unconfirmed_assoc	--tracker.min_iou_threshold_unconfirmed_assoc
--tracker.iou	--tracker.iou_variant

These short forms are CLI aliases only. The Python constructor keywords are unchanged, so ByteTrackTracker(minimum_iou_threshold=0.3) stays correct, and so do tune --fixed_params, each tracker's search_space keys, and the "Valid parameters" list printed on a search_space error. A consequence worth knowing: tune reports the long parameter names, so its output cannot be pasted verbatim into a track command — abbreviate the leading minimum_ or maximum_ token first.

Hyphens and underscores

Interchangeable in every option name, on every command, without a warning. Only the name is rewritten: each - after the leading -- becomes _, and values are left alone, so --detection.model rfdetr-base and --source my-dir/clip.mp4 keep their hyphens. This covers dotted paths and negations alike — --show.no-ids, --tracker.min-iou-threshold and --no-display all reach the parser as their underscore spellings. The canonical documentation spelling uses underscores.

Anything after a bare -- is passed through untouched.

This holds for the deprecated spellings in the tables below too, so a develop command ports without also having to guess which separator each option wanted: --no-boxes and --no_boxes resolve alike, as do --mot-output and --mot_output, --track-ids and --track_ids. --help lists the underscore spelling.

eval prediction inputs

--tracker names the tracking algorithm in track and tune. In eval it meant something else entirely — a file of results that algorithm had already produced. Both prediction inputs are renamed so one option name no longer carries two meanings:

Legacy argument	Current argument
--tracker	--predictions
--tracker_dir	--predictions_dir

The old spellings still parse and warn.

Other commands

Command	Hyphenated spelling	Canonical underscore spelling
eval	--gt-dir	--gt_dir
eval	--predictions-dir	--predictions_dir
tune	--gt-dir	--gt_dir
tune	--detections-dir	--detections_dir
tune	--n-trials	--n_trials
tune	--fixed-params	--fixed_params
tune	--images-dir	--images_dir
tune	--no-enqueue-defaults	--no_enqueue_defaults
download	--cache-dir	--cache_dir

The remaining deprecated transitions are:

Command	Legacy argument	Current argument
eval, tune, download	-o	--output
eval	--metrics CLEAR HOTA	--metrics '["CLEAR", "HOTA"]'
eval	--columns MOTA HOTA	--columns '["MOTA", "HOTA"]'
tune	--metrics CLEAR HOTA	--metrics '["CLEAR", "HOTA"]'
download	positional DATASET	--name DATASET
download	--dataset	--name
download	--list	--list_available

For example, replace:

trackers download mot17 --cache-dir .cache

with:

trackers download --name mot17 --cache_dir .cache

YAML configuration

The same nesting is used in --config files. Command-line values override configuration values.

source: source.mp4
detection:
  model: rfdetr-base
  confidence: 0.3
tracker:
  name: bytetrack
  lost_track_buffer: 40
output:
  video: tracked.mp4
  overwrite: true
display: false
show:
  boxes: false

Run it with:

trackers track --config tracking.yaml