Skip to main content
Change of provenance

The repository or configuration that created this release differ from a previous release. View details.

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 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.

Install

pip install -U reid
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 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.

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("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.

Pretrained models

Name Architecture Trained on Use for
osnet_x1_0_msmt17_combineall 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.0

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

Change of provenance

The repository or configuration that created these release files differ from that of a previous release.

We recommend inspecting the repository and configuration before proceeding. View details.

Source distribution (sdist)

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

Built distribution (wheel)

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

Total release size: 122.2 kB

Release files / reid-0.1.0.tar.gz

Change of provenance

This file belongs to a release with changed provenance: the repository or configuration that created the release files differ from that of a previous release.

We recommend inspecting the repository and configuration before proceeding. View details.

Download URL reid-0.1.0.tar.gz
Size 67.5 kB
Tags Source
SHA-256 checksum
How to use checksums
ce99c79964457bf18d14612db78d4707d43819aed5d848697ab6dfd1412204b9
BLAKE2b-256 checksum
How to use checksums
0839f52f5f7b72b52f1fbf80bbe1e98cc6b66c4fe8490eaaf2df52232f871c4c
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 Nov 3, 2026.

Transparency log

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

Change of provenance

This file belongs to a release with changed provenance: the repository or configuration that created the release files differ from that of a previous release.

We recommend inspecting the repository and configuration before proceeding. View details.

Download URL reid-0.1.0-py3-none-any.whl
Size 54.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
7a9ddb03b481fa3d714ab096c23c6e9ac3e09006cdedfcc3635a843d47c52a92
BLAKE2b-256 checksum
How to use checksums
a87cb7e1465579c4f5358ee1bcbb42dfaae2ab0520ae49c97c54bde58193986d
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 Nov 3, 2026.

Transparency log

Security for reid 0.1.0

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.

Change of provenance

The configuration that created this release differs from a previous release.

While this could reflect a routine change by the project maintainers, it may also indicate that the release files have been compromised.

Select from 2 files

Attestation for reid-0.1.0.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 Nov 3, 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