reid turns a person crop into an appearance embedding, a vector that is close for crops of the same person and far apart for different people. It loads pretrained OSNet and FastReID checkpoints, embeds supervision.Detections from any detector or crops saved on disk, and measures how well a model matches people: across cameras with retrieval on Market-1501 and MSMT17, or over time with re-association on crops cut from MOT-format video. Requires Python 3.10 or newer.

Gallery retrieval with osnet_x1_0_msmt17_combineall: crops ranked by cosine distance to a query player, closest first. The other pretrained models work the same way.

Read the documentation for guides and the API reference.

pip install -U reid

pip install git+https://github.com/roboflow/re-ID.git

extract_embeddings computes one embedding for each bounding box in a frame. Pass the boxes as sv.Detections, which you can get from a detector like RF-DETR. Below, two people are boxed in the first frame of a sample video. from_pretrained downloads the model you name, here OSNet x1.0 trained on MSMT17.

import numpy as np
import supervision as sv
from supervision.assets import VideoAssets, download_assets
from reid import ReIDModel

model = ReIDModel.from_pretrained("osnet_x1_0_msmt17_combineall")

frame = next(sv.get_video_frames_generator(download_assets(VideoAssets.PEOPLE_WALKING)))
detections = sv.Detections(xyxy=np.array([[746, 446, 828, 628], [1136, 502, 1214, 660]], dtype=np.float32))
embeddings = model.extract_embeddings(detections, frame)

embeddings.shape
# (2, 512)

Crops already saved as images work the same way:

embeddings = model.extract_embeddings_from_paths(["crop_1.jpg", "crop_2.jpg"])

For every way to load a model, including saved models, Hugging Face repositories, and weights files, see the loading guide.

There are two ways to build a model: ReIDModel.from_pretrained("osnet_x1_0_msmt17_combineall") loads trained weights, and ReIDModel("osnet_x1_0") builds the architecture with random weights.

model.evaluate scores a model on benchmark splits or on your own identity folders, one folder of crops per person.

from reid import ReIDModel, load_identity_folders, load_market1501

model = ReIDModel.from_pretrained("osnet_x1_0_msmt17_combineall")

query, gallery = load_market1501("/path/to/Market-1501")
result = model.evaluate(query, gallery)

result = model.evaluate(load_identity_folders("/path/to/identity/folders"))
result.metrics
# {'map': ..., 'rank1': ..., 'rank5': ..., 'rank10': ..., 'minp': ...}

For crops cut from video, ReassociationProtocol asks whether the model recognizes a person a set number of frames later, the way a tracker uses it. See the evaluation guide and the metric definitions.

list_aliases() lists these names. Any timm:<name> backbone and other OSNet sizes load from a weights file; see the loading guide.

How to Use Re-ID
Load a model, match the boxes of a MOT17 frame to a later frame with distance_matrix, see identities cluster, and evaluate with retrieval and re-association.

How to Benchmark Re-ID Models
Evaluate OSNet x1.0 on Market-1501 and MSMT17 and compare against the torchreid model zoo.

If you use reid in academic work, please cite the library:

@software{roboflow_reid,
  author  = {{Roboflow}},
  title   = {Roboflow Re-ID},
  url     = {https://github.com/roboflow/re-ID},
  year    = {2026},
  license = {Apache-2.0}
}

For the models themselves, cite OSNet (Zhou et al., ICCV 2019) and FastReID (He et al., 2020).

The code is released under the Apache 2.0 license.