# How to Use YOLOX with BoxMOT for Detection and Tracking

> Learn how to use YOLOX with BoxMOT for advanced object detection and tracking. Integrate YOLOX models effortlessly for real-time multi-object tracking using the CLI or Python API.

- Repository: [Mike/boxmot](https://github.com/mikel-brostrom/boxmot)
- Tags: how-to-guide
- Published: 2026-03-07

---

**BoxMOT integrates YOLOX detection models through automatic model-type routing in `boxmot.detectors` and the `YoloXStrategy` inference class, enabling seamless multi-object tracking via CLI or Python API.**

The **BoxMOT** repository provides a unified framework for multi-object tracking that supports multiple detector backends, including the popular **YOLOX** architecture. By leveraging specific filename patterns and dedicated inference strategies, BoxMOT automatically handles model loading, preprocessing, and post-processing for YOLOX variants. This guide explains how to use YOLOX with BoxMOT for detection and tracking, covering both command-line workflows and programmatic integration.

## YOLOX Integration Architecture

BoxMOT's YOLOX support is built on three core components that work together to route detection requests, execute inference, and manage model weights.

### Model-Type Routing

The entry point for YOLOX detection begins in [`boxmot/detectors/__init__.py`](https://github.com/mikel-brostrom/boxmot/blob/main/boxmot/detectors/__init__.py), where the `get_yolo_inferer` function examines the detector filename or CLI string. If the name contains any YOLOX substring—`yolox_n`, `yolox_s`, `yolox_m`, `yolox_l`, or `yolox_x`—the router selects the YOLOX inference class automatically.

```python

# From boxmot/detectors/__init__.py (lines 22-33)

# Logic that maps model names to YoloXStrategy

if any(x in str(detector) for x in ['yolox_n', 'yolox_s', 'yolox_m', 'yolox_l', 'yolox_x']):
    from boxmot.detectors.yolox import YoloXStrategy
    return YoloXStrategy

```

This routing mechanism allows you to specify YOLOX models by name without manually importing classes or configuring backends.

### YoloXStrategy Implementation

The `YoloXStrategy` class in [`boxmot/detectors/yolox.py`](https://github.com/mikel-brostrom/boxmot/blob/main/boxmot/detectors/yolox.py) implements the complete detect-preprocess-postprocess pipeline. It mirrors the official YOLOX loading routine and automatically downloads pretrained weights from the built-in **YOLOX_ZOO** if the `.pt` file does not exist locally via `download_file` from `boxmot.utils.download`.

Key capabilities of this strategy include:
- **Automatic dependency management**: Uses `RequirementsChecker` to install the `yolox` package if missing
- **Device optimization**: Includes MPS (Apple Silicon) support through monkey-patching of `YOLOXHead.decode_outputs` to avoid dtype-string issues
- **Flexible input handling**: Accepts numpy arrays or torch tensors depending on the pipeline stage

### CLI Command Mapping

The tracking CLI in [`boxmot/engine/cli.py`](https://github.com/mikel-brostrom/boxmot/blob/main/boxmot/engine/cli.py) accepts a positional `detector` argument (or the `--yolo-model` option) that gets forwarded to the routing logic. When you supply a YOLOX model name, the CLI creates a `YoloXStrategy` instance at lines 10-15 and executes the tracking loop starting at line 17.

## Step-by-Step Usage

Follow these steps to run YOLOX-based detection and tracking with BoxMOT.

### 1. Install Dependencies

While BoxMOT can install YOLOX automatically via `RequirementsChecker` when first used, you may pre-install the package:

```bash
pip install yolox

```

### 2. Run Tracking via CLI

Use the `track` command with any supported YOLOX model filename. The name must contain the YOLOX substring for proper routing:

```bash

# Track using YOLOX-S with DeepOCSORT tracker

boxmot track yolox_s.pt osnet_x0_25_msmt17 deepocsort \
    --source video.mp4 \
    --show

```

BoxMOT will:
1. Resolve `yolox_s.pt` → `YoloXStrategy` via `get_yolo_inferer`
2. Download weights from `YOLOX_ZOO` if missing
3. Initialize the model with default image size `[1080, 1920]`
4. Run detection on each frame and feed results to the specified tracker

### 3. Use Custom Checkpoints

Provide a path containing the YOLOX substring to use custom-trained weights:

```bash
boxmot track my_yolox_custom_MOT20.pt osnet_x0_25_msmt17 strongsort \
    --source 0  # webcam input

```

The routing logic applies the same `YoloXStrategy` class, but BoxMOT will not overwrite your local checkpoint file.

### 4. Generate Detections in Batch

For offline processing or embedding generation, use the `generate` command with multiple YOLOX models:

```bash
boxmot generate yolox_x.pt yolox_n.pt \
    osnet_x0_25_msmt17 \
    --source /data/videos \
    --imgsz 1080 1920

```

## Advanced Configuration Options

### Image Size Adjustment

YOLOX defaults to `[1080, 1920]` (stored in `YoloXStrategy.default_imgsz`). Override this for different input resolutions:

```bash
boxmot track yolox_m.pt osnet_x0_25_msmt17 botsort \
    --source video.mp4 \
    --imgsz 720 1280

```

The size parameter is stored in `YoloXStrategy.imgsz` and passed to `yolox_preprocess` during inference.

### Class-Specific Detection

Restrict detection to specific COCO class IDs using the `--classes` flag. The YOLOX post-processing pipeline respects this filter:

```bash
boxmot track yolox_l.pt osnet_x0_25_msmt17 deepocsort \
    --source video.mp4 \
    --classes 0 1 2  # person, bicycle, car only

```

### Python API Integration

For custom pipelines, instantiate `YoloXStrategy` directly:

```python
from boxmot.detectors.yolox import YoloXStrategy
from pathlib import Path
import torch

# Path to model (auto-downloads if missing)

model_path = Path("yolox_s.pt")
device = torch.device("cuda:0" if torch.cuda.is_available() else "cpu")

# Initialize strategy

strategy = YoloXStrategy(model_path, device, args=None)

# im can be list of numpy images (H,W,3) or 4-D torch tensor [B,3,H,W]

preds = strategy(im, augment=False, visualize=False, embed=False)

```

## Key Implementation Details

**Automatic Weight Management**: If the specified `.pt` file is absent, `YoloXStrategy.__init__` triggers `download_file` to fetch weights from the URLs defined in `YOLOX_ZOO`, ensuring zero-configuration deployment.

**Hardware Compatibility**: The YOLOX module specifically handles MPS device quirks by patching `YOLOXHead.decode_outputs`, preventing dtype-related crashes on Apple Silicon hardware.

**Strategy Pattern**: The separation between [`boxmot/detectors/__init__.py`](https://github.com/mikel-brostrom/boxmot/blob/main/boxmot/detectors/__init__.py) (routing) and [`boxmot/detectors/yolox.py`](https://github.com/mikel-brostrom/boxmot/blob/main/boxmot/detectors/yolox.py) (implementation) allows BoxMOT to support multiple detector families while maintaining clean, backend-specific preprocessing logic.

## Summary

- **BoxMOT** routes YOLOX models automatically when filenames contain `yolox_n`, `yolox_s`, `yolox_m`, `yolox_l`, or `yolox_x` substrings via [`boxmot/detectors/__init__.py`](https://github.com/mikel-brostrom/boxmot/blob/main/boxmot/detectors/__init__.py).
- The **`YoloXStrategy`** class in [`boxmot/detectors/yolox.py`](https://github.com/mikel-brostrom/boxmot/blob/main/boxmot/detectors/yolox.py) handles complete inference, including automatic weight downloads from `YOLOX_ZOO`.
- Use the CLI commands `boxmot track` or `boxmot generate` with YOLOX model names to execute detection and tracking pipelines immediately.
- Default image size is **1080×1920**, configurable via `--imgsz`, with full support for class filtering and custom checkpoints.
- The implementation includes **MPS compatibility patches** and lazy dependency installation for streamlined deployment.

## Frequently Asked Questions

### What YOLOX model variants does BoxMOT support?

BoxMOT supports all standard YOLOX variants including `yolox_n` (nano), `yolox_s` (small), `yolox_m` (medium), `yolox_l` (large), and `yolox_x` (extra large). The detection routing in [`boxmot/detectors/__init__.py`](https://github.com/mikel-brostrom/boxmot/blob/main/boxmot/detectors/__init__.py) recognizes these substrings in any filename, including custom-trained checkpoints like `yolox_x_MOT17_ablation.pt`.

### How does BoxMOT handle missing YOLOX weights?

When you specify a YOLOX model that isn't present locally, the `YoloXStrategy.__init__` method automatically calls `download_file` from `boxmot.utils.download`. This fetches the appropriate pretrained weights from the built-in `YOLOX_ZOO` URL mappings, downloading them to your working directory before initializing the model.

### Can I use YOLOX with BoxMOT on Apple Silicon (MPS)?

Yes, BoxMOT includes specific patches for MPS compatibility. The [`boxmot/detectors/yolox.py`](https://github.com/mikel-brostrom/boxmot/blob/main/boxmot/detectors/yolox.py) file monkey-patches `YOLOXHead.decode_outputs` to resolve dtype-string issues that occur when running YOLOX on Apple Silicon devices, ensuring the detection pipeline runs without modification on MPS hardware.

### What is the default input size for YOLOX in BoxMOT?

YOLOX models in BoxMOT default to an input size of **1080×1920** (height × width), stored in `YoloXStrategy.default_imgsz`. You can override this using the `--imgsz` CLI flag or by modifying the `imgsz` attribute when using the Python API directly.