# How to Add New ReID Backbone Networks to BoxMOT: A Step-by-Step Implementation Guide

> Easily add new ReID backbone networks to BoxMOT with this step-by-step guide. Learn to implement, register, and update configurations for seamless multi-object tracking integration.

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

---

**To add a new ReID backbone to BoxMOT, implement the architecture in `boxmot/reid/backbones/`, register the constructor in [`boxmot/reid/core/factory.py`](https://github.com/mikel-brostrom/boxmot/blob/main/boxmot/reid/core/factory.py), and update the model registry in [`boxmot/reid/core/config.py`](https://github.com/mikel-brostrom/boxmot/blob/main/boxmot/reid/core/config.py) to enable automatic instantiation during multi-object tracking.**

BoxMOT, maintained in the `mikel-brostrom/boxmot` repository, is a widely-used open-source multi-object tracking framework that combines object detection with Re-identification (ReID) for robust tracking across frames. Integrating custom ReID backbone networks allows researchers to optimize feature extraction for specific surveillance domains or deploy lightweight architectures for edge devices. This guide details the exact implementation steps required to add new PyTorch-compatible ReID models to BoxMOT based on the current source code architecture.

## Understanding the ReID Factory Architecture

BoxMOT employs a **factory pattern** to manage ReID model instantiation. The `ReIDModelRegistry` class in [`boxmot/reid/core/registry.py`](https://github.com/mikel-brostrom/boxmot/blob/main/boxmot/reid/core/registry.py) provides a `build_model()` method that dynamically constructs model instances by looking up constructor functions in the `MODEL_FACTORY` dictionary defined in [`boxmot/reid/core/factory.py`](https://github.com/mikel-brostrom/boxmot/blob/main/boxmot/reid/core/factory.py). This design decouples model definitions from the tracking logic, allowing new backbones to be added without modifying the core tracking algorithms.

The architecture also leverages `ReidAutoBackend` to automatically handle different inference backends (PyTorch, ONNX, TensorRT). As long as your backbone follows the standard PyTorch API—including a `get_features()` method—it will be compatible with the existing `PyTorchBackend` without additional modifications.

## Step 1: Create the Backbone Implementation

Create a new Python file in `boxmot/reid/backbones/` that defines your architecture. Follow the structure of existing implementations like [`resnet.py`](https://github.com/mikel-brostrom/boxmot/blob/main/resnet.py) or [`osnet.py`](https://github.com/mikel-brostrom/boxmot/blob/main/osnet.py), ensuring your function returns a `torch.nn.Module`.

Your implementation must expose a constructor function that accepts standard parameters: `num_classes`, `loss`, `pretrained`, and optional keyword arguments. If your model supports pretrained weights, implement the loading logic within this function.

Add the function name to the module's `__all__` list to maintain a clean public API, following the convention seen in [`resnet.py`](https://github.com/mikel-brostrom/boxmot/blob/main/resnet.py) where `__all__ = ["resnet18", "resnet34", "resnet50", "resnet50_fc512"]`.

## Step 2: Register the Model in the Factory

Edit [`boxmot/reid/core/factory.py`](https://github.com/mikel-brostrom/boxmot/blob/main/boxmot/reid/core/factory.py) to import your new constructor and add it to the `MODEL_FACTORY` dictionary. This dictionary maps unique string identifiers to constructor functions.

For example, if you created a backbone named `tiny_resnet`, add the import statement at the top of the file and insert the mapping `"tiny_resnet": tiny_resnet` into the `MODEL_FACTORY` dictionary alongside existing entries like `"resnet50"` and `"osnet_x1_0"`.

## Step 3: Update the Configuration Registry

Modify [`boxmot/reid/core/config.py`](https://github.com/mikel-brostrom/boxmot/blob/main/boxmot/reid/core/config.py) to register your model name in two locations. First, append the new name to the `MODEL_TYPES` list so the auto-backend can recognize and validate the model identifier during configuration parsing.

Second, if you provide pretrained weights, add a download URL to the `TRAINED_URLS` dictionary using the model name as the key. This enables BoxMOT's automatic weight downloading utilities to fetch your checkpoint when users specify the model in their YAML configurations.

## Step 4: Configure Your Tracking Pipeline

Create or modify a YAML configuration file to use your new backbone. Set the `reid.model_name` parameter to the string identifier you registered in the factory, and specify the path to your trained weights in `reid.weights`.

BoxMOT will automatically instantiate your model via `ReIDModelRegistry.build_model()`, load the specified weights, and integrate the backbone into the tracking pipeline without requiring further code changes.

## Complete Implementation Example

The following example demonstrates adding a fictional `tiny_resnet` backbone optimized for fast inference.

First, implement the architecture:

```python

# boxmot/reid/backbones/tiny_resnet.py

import torch.nn as nn
from boxmot.reid.backbones.resnet import ResNet, Bottleneck

def tiny_resnet(num_classes, loss="softmax", pretrained=False, **kwargs):
    """A lightweight ResNet variant for edge deployment."""
    model = ResNet(
        num_classes=num_classes,
        loss=loss,
        block=Bottleneck,
        layers=[1, 1, 1, 1],  # shallow architecture

        last_stride=2,
        fc_dims=None,
        dropout_p=None,
        **kwargs,
    )
    if pretrained:
        # Load custom checkpoint logic here

        pass
    return model

__all__ = ["tiny_resnet"]

```

Next, register the constructor in the factory:

```python

# boxmot/reid/core/factory.py

from boxmot.reid.backbones.tiny_resnet import tiny_resnet  # Add import

MODEL_FACTORY = {
    # Existing entries...

    "osnet_x1_0": osnet_x1_0,
    "resnet50": resnet50,
    "tiny_resnet": tiny_resnet,  # Add registration

}

```

Then, update the configuration:

```python

# boxmot/reid/core/config.py

MODEL_TYPES = [
    # Existing types...

    "resnet50",
    "osnet_x1_0",
    "tiny_resnet",  # Add to registry

]

TRAINED_URLS = {
    # Optional: Add pretrained weight URLs

    "tiny_resnet": "https://example.com/tiny_resnet_market1501.pth",
}

```

Finally, use the model in your tracking configuration:

```yaml

# config.yaml

reid:
  model_name: tiny_resnet
  weights: path/to/tiny_resnet_market1501.pt
  loss: softmax

```

## Key Technical Considerations

When implementing custom backbones, ensure your model class implements a `get_features()` method that returns embedding vectors. The `ReidAutoBackend` inspects the weight file suffix to determine the inference backend, but the model architecture itself must conform to the PyTorch API expectations defined in [`boxmot/reid/core/registry.py`](https://github.com/mikel-brostrom/boxmot/blob/main/boxmot/reid/core/registry.py).

The factory pattern in [`boxmot/reid/core/factory.py`](https://github.com/mikel-brostrom/boxmot/blob/main/boxmot/reid/core/factory.py) centralizes model construction, while [`boxmot/reid/core/config.py`](https://github.com/mikel-brostrom/boxmot/blob/main/boxmot/reid/core/config.py) maintains the canonical list of supported architectures. This separation ensures that adding new ReID backbone networks to BoxMOT requires changes only to the model definition and registration files, leaving the core tracking logic untouched.

## Summary

- **Implement** your backbone in `boxmot/reid/backbones/` following existing patterns like [`resnet.py`](https://github.com/mikel-brostrom/boxmot/blob/main/resnet.py) and [`osnet.py`](https://github.com/mikel-brostrom/boxmot/blob/main/osnet.py).
- **Register** the constructor function in [`boxmot/reid/core/factory.py`](https://github.com/mikel-brostrom/boxmot/blob/main/boxmot/reid/core/factory.py) by adding an entry to the `MODEL_FACTORY` dictionary.
- **Configure** the model type in [`boxmot/reid/core/config.py`](https://github.com/mikel-brostrom/boxmot/blob/main/boxmot/reid/core/config.py) by appending to `MODEL_TYPES` and optionally `TRAINED_URLS`.
- **Deploy** by referencing the model name in your YAML configuration files; the `ReIDModelRegistry` handles automatic instantiation.

## Frequently Asked Questions

### What file should I edit to register a new ReID backbone in BoxMOT?

Edit [`boxmot/reid/core/factory.py`](https://github.com/mikel-brostrom/boxmot/blob/main/boxmot/reid/core/factory.py) to import your constructor and add it to the `MODEL_FACTORY` dictionary. You must also update [`boxmot/reid/core/config.py`](https://github.com/mikel-brostrom/boxmot/blob/main/boxmot/reid/core/config.py) to include the model name in `MODEL_TYPES` so the configuration validator recognizes the identifier.

### Does BoxMOT support pretrained weights for custom ReID models?

Yes. Add your pretrained weight URLs to the `TRAINED_URLS` dictionary in [`boxmot/reid/core/config.py`](https://github.com/mikel-brostrom/boxmot/blob/main/boxmot/reid/core/config.py). When users specify your model name in a configuration file, BoxMOT will automatically download the weights if they are not present locally.

### Where does the factory pattern instantiate ReID models in BoxMOT?

The `ReIDModelRegistry.build_model()` method in [`boxmot/reid/core/registry.py`](https://github.com/mikel-brostrom/boxmot/blob/main/boxmot/reid/core/registry.py) performs the instantiation. It looks up the model name in `MODEL_FACTORY` from [`boxmot/reid/core/factory.py`](https://github.com/mikel-brostrom/boxmot/blob/main/boxmot/reid/core/factory.py) and calls the associated constructor with parameters from the YAML configuration.

### Can I use ONNX or TensorRT backends with custom ReID backbones?

Yes. The `ReidAutoBackend` class automatically selects the appropriate backend based on the weight file extension. As long as your custom backbone follows the standard PyTorch API and you export it to ONNX or TensorRT format, the existing backend implementations will handle inference without requiring modifications to your model code.