Skip to main content

PyTorch Metric Learning

Train embedding models with composable PyTorch losses, hard-example miners, distances, reducers, and regularizers. Use them in your own training loop for retrieval, clustering, recognition, or learning from pairs and triplets.

Docs for humans · Documentation source

How embeddings flow through miners, losses, reducers, and retrieval metrics.

Install

Install from PyPI with uv or pip:

uv pip install pytorch-metric-learning
pip install pytorch-metric-learning

The core package needs only PyTorch and NumPy. Optional extras add the Faiss retrieval backend, pytorch-metric-learning[faiss], and scikit-learn for the NMI/AMI clustering metrics, pytorch-metric-learning[clustering].

Version 3 requires Python 3.12 or newer, PyTorch 2.14.0 or newer, and NumPy 2.5.3 or newer. Upgrading from version 2? Read the release notes and look up old names in the migration guide. The version 2 documentation remains available.

A minimal training step

Your model produces one embedding per input. Equal labels identify positive pairs; different labels identify negatives. Here a contrastive loss pulls positive pairs together and pushes negatives apart:

import torch
from pytorch_metric_learning import losses

torch.manual_seed(17)
model = torch.nn.Linear(8, 4)
optimizer = torch.optim.SGD(model.parameters(), lr=0.1)
data = torch.randn(12, 8)
labels = torch.arange(4).repeat_interleave(3)
loss_func = losses.ContrastiveLoss(neg_margin=1.4)

optimizer.zero_grad(set_to_none=True)
loss = loss_func(model(data), labels)
loss.backward()
optimizer.step()

The model returns embeddings shaped (12, 4) and labels have shape (12,). This loss L2-normalizes embeddings by default. It averages active positive and negative pair penalties separately, then adds them. See the contrastive-loss contract for distances, margins, and reduction options.

Learn more

The documentation starts with a task index and a concepts overview of embeddings, tuples, distances, loss terms, and reducers. Every component page states its signature, defaults, tensor contract, and paper, and the recipes show complete training and evaluation code.

Contributing

See CONTRIBUTING.md. Thanks to all contributors, upstream projects, and supporters.

Citing this library

If you use this library in your research, please cite the PyTorch Metric Learning paper:

@article{Musgrave2020PyTorchML,
  title={PyTorch Metric Learning},
  author={Kevin Musgrave and Serge J. Belongie and Ser-Nam Lim},
  journal={ArXiv},
  year={2020},
  volume={abs/2008.09164}
}

Metadata

Release files for pytorch-metric-learning 3.0.4

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

Source distribution (sdist)

Source distribution for pytorch-metric-learning 3.0.4
File Size Uploaded Provenance Actions
pytorch_metric_learning-3.0.4.tar.gz 70.4 kB Without provenance Details for pytorch_metric_learning-3.0.4.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pytorch-metric-learning 3.0.4
File Interpreter ABI Platform Actions
pytorch_metric_learning-3.0.4-py3-none-any.whl Python 3 none any Details for pytorch_metric_learning-3.0.4-py3-none-any.whl

Total release size: 189.1 kB

Release files / pytorch_metric_learning-3.0.4.tar.gz

Download URL pytorch_metric_learning-3.0.4.tar.gz
Size 70.4 kB
Tags Source
SHA-256 checksum
How to use checksums
1c80e1b42f98790dc75f2fa20bf11e52f0f36235ec3be658d26f5f28ea91e98d
BLAKE2b-256 checksum
How to use checksums
19e6ff67bf9d8de8ce59ba4bcb73627b837c8a1cf653e64591c4cce97b3f168b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.4 {"installer":{"name":"uv","version":"0.13.4","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / pytorch_metric_learning-3.0.4-py3-none-any.whl

Download URL pytorch_metric_learning-3.0.4-py3-none-any.whl
Size 118.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f50aa0bf42703f603eb35b4d5f440f259569b60ff6434f96c461703bff31be31
BLAKE2b-256 checksum
How to use checksums
0ca5aa3dd4fc1dd142f323286af75526ac968baf3da9d27f6dfd7aec7fa45a86
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.4 {"installer":{"name":"uv","version":"0.13.4","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for pytorch-metric-learning 3.0.4

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.

No provenance found

None of the files in this release were uploaded with provenance metadata.

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.

Release history Release notifications | RSS feed

This release

3.0.4 This release

2 release files No provenance

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