pytorch-metric-learning

What it is and what it does

pytorch-metric-learning is a PyTorch library for training neural networks to produce embeddings where semantically similar inputs are close together and dissimilar ones are far apart. It provides loss functions (TripletMarginLoss, SmoothAPLoss, ArcFace variants, and others), hard-pair miners that identify difficult training examples, distance metrics, and evaluation tools. The library is modular: each component—losses, miners, distances, reducers, regularizers—can be used independently or composed together. It supports both supervised learning (where labels define similarity) and self-supervised approaches like MoCo-style momentum encoding.

You integrate it into a standard PyTorch training loop by computing embeddings from your model, passing them to a loss function along with labels, and optionally using a miner to focus on hard examples. The library handles the combinatorial complexity of forming triplets or pairs from batches automatically. It includes convenience modules for dataset downloading (CUB200, Cars196, INaturalist, Stanford Online Products), training workflows, and accuracy calculation on standard benchmarks.

Use it for:

• Train face recognition or person re-identification models where embeddings must cluster by identity.
• Build product recommendation systems by learning embeddings where similar items are nearby in embedding space.
• Implement image retrieval systems where query and gallery images are ranked by embedding similarity.
• Train self-supervised models using contrastive objectives without labeled data.
• Evaluate embedding quality on standard benchmarks using built-in accuracy calculators and testers.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Provides metric learning loss functions, miners, and evaluation tools for training deep neural networks to learn embeddings where similar items cluster together and dissimilar items separate.

Yes, with a minor caveat on maintenance timing. The library is well-established (6336 stars, top 5000 PyPI), permissively licensed, and has low install friction. Its modular design and comprehensive loss/miner suite make it the standard choice for metric learning in PyTorch. However, the last release was 362 days ago; if you need very recent bug fixes or features, verify that the current version addresses your use case or check the development branch.

Install

pytorch-metric-learning on PyPI

pip install pytorch-metric-learning

uv add pytorch-metric-learning

poetry add pytorch-metric-learning

Installing pytorch-metric-learning

Before you install

Low friction installation with four core runtime dependencies (numpy, scikit-learn, torch, tqdm). Maintenance status is aging—last release was 362 days ago—but the repository remains active with 6336 stars and no archived status.

License in practice

MIT license permits commercial and private use with minimal restrictions, making it suitable for most projects without legal concern.

Quickstart

pip install pytorch-metric-learning

from pytorch_metric_learning import losses
loss_func = losses.TripletMarginLoss()

# In training loop:
embeddings = model(data)
loss = loss_func(embeddings, labels)
loss.backward()

Requires torch >= 1.6 for pytorch-metric-learning >= v0.9.90; earlier versions have no strict torch version requirement but were tested with torch >= 1.2.

Verify before relying

• Whether the library's 9 modules can all be used independently or if some have undocumented interdependencies.
• Performance characteristics or scalability limits when training on very large batches or high-dimensional embeddings.
• Whether optional dependencies (faiss-gpu, faiss-cpu, record-keeper, tensorboard) are truly optional or required for core functionality.

Package facts

Evidence: pytorch_metric_learning-2.9.0-py3-none-any.whl

Tags

More Artificial Intelligence packages