Skip to content

Upgrading sentence-transformers 4 to 5

Breaking4.1.0 → 5.7.0Breaking4Security3Platform1Deprecated2New40Changed280Fixed108Other101

Full comparisonBack to sentence-transformers
BreakingUpgrade verdict

4 breaking changes and a platform requirement change and 3 security fixes.

In plain terms
  • Custom training loops that run two forward passes before one backward pass now get correct gradients. The `.cache` and `.random_states` loss attributes are removed.
  • No longer crash if CrossEncoder.predict is called with an empty list.
  • Training with large batches at constant memory now uses one shared implementation, which fixes several bugs that quietly produced incorrect training updates.
  • The default weighting of earlier-layer losses changed; pass layer_weighting="linear" to keep the old behavior.
Must act Top 5 of 10 that need code or config changes

sentence-transformers publishes an official migration guide for version 5. It covers more than the release notes do.

Migration Guide ↗

Python requirement changed in 5.2.0: >=3.9 → >=3.10.

Adds numpy >=1.20.0, tokenizers >=0.19.

Drops pillow.

Installs 59 packages in all (was 51).

What you must change

Breaking4
Moves the gradient cache from the loss module to each forward pass's backward hook, so two forward passes before a backward no longer backpropagate the wrong batch.
CachedGISTEmbedLoss.cache.random_states
5.7.0GitHub ReleaseSummarizedView source
No longer crash if CrossEncoder.predict is called with an empty list.
CrossEncoder.predict
5.1.0GitHub ReleaseOriginalView source
Rebuilds all gradient-cached losses on one shared engine, fixing silently wrong gradients and adding token-based mini-batching.
CachedMultipleNegativesRankingLossCachedGISTEmbedLossCachedSpladeLossMegaBatchMarginLoss
5.7.0GitHub ReleaseSummarizedView source
Adds a configurable layer_weighting option to AdaptiveLayerLoss and Matryoshka2dLoss, defaulting to uniform instead of the previous 1/(1+layer_idx) decay.
AdaptiveLayerLossMatryoshka2dLosslayer_weighting
5.7.0GitHub ReleaseSummarizedView source
Security3
Creates a Security Policy.
5.7.0GitHub ReleaseSummarizedView source
Trust-checks every non-sentence-transformers module class import.
5.7.0GitHub ReleaseSummarizedView source
sentence-transformers local model loading bypasses trust_remote_code and executes custom Python
Critical · CVSS 9.8
5.6.0GitHub AdvisoryOriginalView source
Platform1
[deprecation] Deprecate Python 3.9, upgrade ruff.
deprecation
5.2.0GitHub ReleaseOriginalView source

Deprecations to plan for

Deprecated2
Trust-checks third-party module class imports from modules.json, emitting a FutureWarning now and requiring trust_remote_code=True from v6.0.
modules.jsontrust_remote_codeWordEmbeddingstokenizer_classmodel_name_or_path
5.7.0GitHub ReleaseSummarizedView source
The deprecated n-tuple-scores format has been replaced with the cleaner output_format="n-tuple" combined with output_scores=True.
n-tuple-scoresoutput_format="n-tuple"output_scores=True
5.2.0GitHub ReleaseOriginalView source