●Change8

Migrating to sentence-transformers v5.2.0

Version v5.2.0 introduces 1 breaking change. This guide details how to update your code.

Released: 12/11/2025

1
Breaking Changes
3
Migration Steps
8
Affected Symbols

⚠️ Check Your Code

If you use any of these symbols, you need to read this guide:

CrossEncoderCrossEncoder.start_multi_process_poolCrossEncoder.stop_multi_process_poolCrossEncoder.predictCrossEncoder.rankmine_hard_negativesNanoBEIREvaluatorSentenceTransformer

Breaking Changes

●Issue #1

The old `n-tuple-scores` output format for `mine_hard_negatives` has been removed; use `output_format=\"n-tuple\"` with `output_scores=True` instead.

Migration Steps

  1. 1
    If you used the old `n-tuple-scores` format, replace it with `output_format=\"n-tuple\"` and set `output_scores=True`.
  2. 2
    Upgrade the `transformers` package to >=5.0 to ensure compatibility.
  3. 3
    When using `CrossEncoder`, initialize a pool with `pool = model.start_multi_process_pool()` and pass `pool=pool` to `predict`/`rank`, then call `model.stop_multi_process_pool(pool)` after inference. Alternatively, pass a list of devices (e.g., `device=[\"cpu\"]*4`).

Release Summary

Version 5.2.0 adds multiprocessing to CrossEncoder, multilingual NanoBEIR support, similarity scores in hard‑negative mining, and updates for Transformers 5 while deprecating Python 3.9 and the old `n-tuple-scores` format.

Need More Details?

View the full release notes and all changes for sentence-transformers v5.2.0.

View Full Changelog