Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

reid

Load and evaluate person re-identification models in Python.

version downloads license python-version discord

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.

https://github.com/user-attachments/assets/68fe0a58-1414-4776-a4a0-412cbcb68643

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

Install

pip install "reid==0.1.0rc1"
Install from source
pip install git+https://github.com/roboflow/re-ID.git

For development, clone the repository and run uv sync --all-extras or pip install -e ".[dev]".

Quick start

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() with no name downloads the default model, 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()

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.

Evaluate

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()

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.

Pretrained models

Name Architecture Trained on Use for
osnet_x1_0_msmt17_combineall (default) OSNet x1.0 MSMT17, all splits combined General pedestrian embeddings. Not for evaluating on MSMT17, whose test identities it has seen.
fastreid_mot17_sbs50 FastReID SBS, ResNeSt-50 MOT17 train-half ground-truth crops MOT17 tracking, as in BoT-SORT
osnet_x1_0_mot17 OSNet x1.0 MOT17 train-half crops Tracking pedestrians, as in MOT17
osnet_x1_0_sportsmot OSNet x1.0 SportsMOT train crops Tracking basketball, football and volleyball players, as in SportsMOT
osnet_x1_0_dancetrack OSNet x1.0 DanceTrack train crops Tracking dancers in similar outfits, as in DanceTrack
osnet_x1_0_soccernet OSNet x1.0 SoccerNet train crops Tracking soccer players, as in SoccerNet

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

Tutorials

A query player and the first eight crops of the gallery ranked by distance, the same player at ranks 1 to 6 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.

Open In Colab


A query player, a gallery of crops, and the gallery ranked by similarity with the matches outlined How to Benchmark Re-ID Models
Evaluate OSNet x1.0 on Market-1501 and MSMT17 and compare against the torchreid model zoo.

Open In Colab


Guides

Guide What you will do
Load a model Load pretrained names, saved models, Hugging Face repositories, and weights files, and set image preprocessing
Evaluate a model Score a model on Market-1501, your own identity folders, or crops cut from video
Understand the metrics Read mAP, rank-k, mINP, and MRR, and see why tracking needs re-association

Citation

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

BibTeX
@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).

License

The code is released under the Apache 2.0 license.

Metadata

Release files for reid 0.1.0rc1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for reid 0.1.0rc1
File Size Uploaded Provenance Actions
reid-0.1.0rc1.tar.gz 67.6 kB With provenance Details for reid-0.1.0rc1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for reid 0.1.0rc1
File Interpreter ABI Platform Actions
reid-0.1.0rc1-py3-none-any.whl Python 3 none any Details for reid-0.1.0rc1-py3-none-any.whl

Total release size: 122.5 kB

Release files / reid-0.1.0rc1.tar.gz

Download URL reid-0.1.0rc1.tar.gz
Size 67.6 kB
Tags Source
SHA-256 checksum
How to use checksums
6a0e63757a7026f4983618ced996eec48924772151e2c71da0fd79e6c2b9821a
BLAKE2b-256 checksum
How to use checksums
5adf57172cbb77f7c447e59644f46830de7c82ff4ce736a85c0d708d95dd651d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 22, 2026.

Transparency log

Release files / reid-0.1.0rc1-py3-none-any.whl

Download URL reid-0.1.0rc1-py3-none-any.whl
Size 54.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
98711940c2f1501b9b404d65e88875981f219746c6c0983b50dd1a6297489904
BLAKE2b-256 checksum
How to use checksums
5119254eed7487d4710e22a3b97d308d9a3acdf0d1cd055cbe03109c8b5d5ba7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 22, 2026.

Transparency log

Security for reid 0.1.0rc1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for reid-0.1.0rc1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 22, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page