# What changed in sentence-transformers

> 83 changes in sentence-transformers 5 to 6 from its official release notes, upgrade guides and advisories: 9 breaking, 2 deprecations, 1 security, 16 new APIs and options. Each one cited. Sources checked 2026-10-28. HTML: https://unstale.sh/pypi/sentence-transformers/

To see which of these apply to a repository, run `npx @unstale/cli init` in it.

## sentence-transformers 6

### Breaking changes

- Module paths must be relative and cannot contain .. path components, including when trust_remote_code=True. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- Normalizes hierarchical token pooling outputs by default. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- Output tokens, including protected tokens, are now normalized by default. Set normalize_embeddings=False to opt out; older saved configurations retain prior behavior. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- Raises a clear error when ranges come from a single embedding. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- Fails fast when a pool worker dies. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- Excludes self-matches before taking top_k and follows only duplicate pairs in the transitive closure. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- Inferring int8 or uint8 calibration ranges from a single vector now raises ValueError; encode representative calibration embeddings first or provide explicit ranges. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- KV caching is disabled by default when supported to reduce unnecessary inference memory use; explicit use_cache overrides in config_kwargs remain honored. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- Message content now follows each input's key order, which can change embeddings or scores. (6.1.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.1.0)

### Deprecations

- Warns when models implicitly load in low precision on CPU. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- The apply_softmax parameter is deprecated. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)

### New APIs and options

- Call after changing dispatch hooks or adding modules following the first inference call. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- Merge compatible fine-tuned checkpoints without another training run; the returned model can be used, trained, and saved normally. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- HierarchicalTokenPooling can use optional fastcluster linkage for faster clustering. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- Adds opt-in fp32 computation for selected linear layers. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- Forwards gradient checkpointing options to Transformers. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- Select CrossEncoder linear layers to compute in FP32, reducing BF16 score ties while keeping a reduced-precision backbone. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- Can be passed through processing_kwargs. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- Adds model merging via mergekit for all archetypes. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- Merge compatible fine-tuned checkpoints without another training run; the returned model can be used, trained, and saved normally. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- Accepts a string main_score_function. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- Merge compatible fine-tuned checkpoints without another training run; the returned model can be used, trained, and saved normally. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- Supports probability targets and matches inputs to the classifier dtype. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- Adds SlideOn and mSlideOn to the pretrained models. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- Merge compatible fine-tuned checkpoints without another training run; the returned model can be used, trained, and saved normally. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- Schedules the regularizer weights of every SpladeLoss. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- Accepts dictionary configurations. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)

### Performance

- Uses sorted suffix reductions with linear intermediate storage. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- Removes invalid anchor-positive pairs before constructing triplets, reducing memory to quadratic for paired labels. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- Uses quadratic intermediate memory instead of constructing cubic distance and mask tensors, and corrects a gradient issue when selected negative distances tie. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- Avoids redundant DDP synchronization during cached-loss replay. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- Uses sorted suffix reductions with linear intermediate storage. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- Computes CoSENT ranking loss with linear-memory suffix reductions. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- Fixes memory use for long query batches. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- Score blocks are budgeted using both query and document token counts, reducing memory use for long query batches. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- With huggingface_hub>=1.26.0, loading resolves the requested branch or tag to a commit once and reuses it across component downloads, reducing repeated Hub requests. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- CPU cosine semantic_search is faster by normalizing each corpus chunk once. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- Handles an empty list corpus and speeds up CPU search by normalizing each corpus chunk once. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)

### Behavior and default changes

- During DDP training, evaluators automatically share encode and predict work across training processes; rank zero combines predictions and computes metrics. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- Accepts fractional pool_factor values for finer control over compression. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- huggingface_hub 2.x is supported; the Hub 1.3.0 minimum is retained. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- CSR training now supports k_aux=0. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- Treats a string positive or negative as one document. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- A single input can contain multiple items per modality. (6.1.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.1.0)

### Fixes and other changes

- Drops communities whose centre was already claimed. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- Checkpoint restoration now works for compiled models, including best-checkpoint loading. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- Honors the progress-bar option. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- Keeps the 4k latents off the dead-latent mask and compares reconstructions with raw input when normalize=True. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- Applies per-dataset prompts and losses when a DatasetDict is reused. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- Validates Dense activation classes before loading. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- Keeps string features whole when output_value=None. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- Keeps pairs that cross the top-k cutoff. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- Only truncates sentence embeddings and truncates per-column teacher labels. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- Fixes mean pooling precision and excludes flattened CLS prompts correctly. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- Uses the supplied CrossEncoder for hard-negative filtering when only min_score is set. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- Validates model paths before loading. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- Validates paired sentence counts. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- Worker exceptions reach the caller, terminated workers are detected while polling, and worker tensor outputs are moved to CPU before queueing. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- Forwards advertised module kwargs during encoding. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- Fixes loading Normalize modules at the model root. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- Normalizes a single sparse embedding as one vector and supports non-default dtypes. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- Counts rank positions from one and stabilizes position weights for long ranking lists. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- Improves FP16/BF16 mean and weighted-mean arithmetic, corrects weighted positions under left padding, and fixes prompt exclusion in flattened CLS fallback selection. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- Python 3.14 is supported while Python 3.10 support is retained. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- Return zero ranking loss when no label pairs are ordered, and preserve gradients with weighted log-sigmoid. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- Keeps modules shared between routes shared after loading. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- Keeps fusion order the same from run to run. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- Reuses scalar calibration ranges across ragged multi-vector embeddings, accepts BF16 inputs, and corrects FP16 range arithmetic. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- Fixes calibration when rescoring scalar-quantized embeddings. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- Optimizes loss weights, spans every objective's steps in the learning-rate schedule, and warns that a DataLoader batch_sampler is not used. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- Supports repeated evaluation with iterator-backed evaluators. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- Uses the corpus model and embeddings during evaluation. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- Prevents new sparse search corpora from sharing an index name. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- Corrects normalization of single sparse vectors and sparse matrices with non-default dtypes or low-precision values. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- Sizes weights by the vocabulary size. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- Accepts duplicate expected translation text. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- Evaluates the main similarity function. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- Pads batches with no known tokens and honors the sequence length limit. (6.2.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.2.0)
- Corrected load_audio_from_video routing in chat templates. (6.1.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.1.0)
- Video-frame URLs without recognizable image extensions need an explicit frame wrapper to remain one video. (6.1.0) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.1.0)
- PyLate prefixes are now prepended to saved prompt text, so checkpoints trained with both encode the marker they were trained with. (6.0.1) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.0.1)
- Router.preprocess now forwards task to routed modules, enabling task-dependent preprocessing such as length caps, query expansion, and the chat-template task keyword. (6.0.1) — [release notes](https://github.com/huggingface/sentence-transformers/releases/tag/v6.0.1)

## sentence-transformers 5

### Security

- sentence-transformers local model loading bypasses trust_remote_code and executes custom Python (5.6.0) — [security advisory](https://github.com/advisories/GHSA-JHR6-GM9C-RQJV)