Upgrading sentence-transformers 5 to 6
Breaking5.7.0 → 6.2.0Breaking15Platform3Deprecated1New45Changed57Fixed157Other55
BreakingUpgrade verdict
15 breaking changes and 3 platform requirement changes.
In plain terms
- Outputs from hierarchical token pooling models are now normalized automatically, which changes the values they return.
- You can no longer replace model.similarity with your own function; set similarity_fn_name instead.
- Converting a model to another type no longer copies inference settings that describe the original model.
- Quantizing from just one vector no longer works. You must encode several representative vectors first or give explicit ranges.
Must act Top 5 of 19 that need code or config changes
sentence-transformers publishes an official migration guide for version 6. It covers more than the release notes do.
Migration Guide ↗What you must change
Breaking15
Normalizes hierarchical token pooling outputs by default.
similarity and similarity_pairwise are now methods, not properties; assigning a custom function to model.similarity is no longer supported.
similaritysimilarity_pairwisesimilarity_fn_namesentence_transformers.util.similarity_fct_name()get_config_dict()Cross-family conversion no longer inherits prompts, default_prompt_name, similarity_fn_name, truncate_dim, or activation_fn from the source model.
SentenceTransformerCrossEncoderpromptsdefault_prompt_namesimilarity_fn_nametruncate_dimactivation_fnInferring int8 or uint8 calibration ranges from a single vector now raises ValueError; callers must pass calibration_embeddings or explicit ranges.
quantize_embeddingscalibration_embeddingsrangesModule paths must be relative and cannot contain .. path components, even with trust_remote_code=True; custom modules must stay inside the checkpoint tree.
trust_remote_codeA bare list of chat message dictionaries is now treated as one conversation instead of a batch of inputs.
model.encodeSentenceTransformerSparseEncoderMultiVectorEncoderCrossEncoderLoading models with custom module classes now requires trust_remote_code=True, closing a code-execution bypass.
trust_remote_codemodules.jsonload_best_model_at_endresume_from_checkpointquantize_embeddings now returns a list of per-input matrices for a list of 2D arrays instead of one stacked 3D array.
quantize_embeddingsMulti-process encode with pool and precision="int8" now quantizes once after merging worker results, so v5.x quantized indexes are not bit-compatible.
encodepoolprecisionCrossEncoder.rank now returns Python floats for scores, and convert_to_numpy and convert_to_tensor on rank are deprecated no-ops.
CrossEncoder.ranksemantic_searchconvert_to_numpyconvert_to_tensorpredictNormalize moved to sentence_transformers.base.modules; models saved by v6.0 with it cannot be loaded by older versions.
Normalizesentence_transformers.base.modulesAutomatically generated model cards now open with "It maps inputs to a N-dimensional dense vector space" instead of "It maps sentences & paragraphs to ...".
CrossEncoder.rank now returns Python floats instead of previous numeric types.
CrossEncoder.rankUnifies document_chunk_elements and pair_chunk_elements into a single chunk_elements.
document_chunk_elementspair_chunk_elementschunk_elementsRequires trust_remote_code=True for custom module classes, dropping implicit local-directory trust.
trust_remote_codePlatform3
Adds Python 3.14 and huggingface_hub 2.x support while retaining Python 3.10 support and the Hub 1.3.0 minimum.
huggingface_hubAdds Python 3.14 support.
Keeps requires-python at >=3.10; multi-GPU training with streaming IterableDataset datasets needs accelerate>=1.13.0 in practice.
IterableDatasetaccelerateDeprecations to plan for
Deprecated1
Deprecates apply_softmax on CrossEncoder.rank.
CrossEncoder.rankapply_softmax