How to migrate Sentence Transformers code to v5

Sentence Transformers v5 keeps the common embedding workflow familiar, but older projects can still carry compatibility imports, argument names, and helper methods that now warn under recent 5.x releases. Migrating those call sites keeps application code aligned with the current API before compatibility paths disappear in a later release.

Recent v5 releases favor the shared package module paths, processor_kwargs for model construction, get_embedding_dimension() for embedding size checks, and inputs= when calling encode(). Retrieval code should also move from prompt-name wiring to encode_query() and encode_document() when the model defines query and document behavior.

Run the migration in a branch or scratch copy of the project. Keep deeper model-architecture changes, such as replacing Asym with Router, in their own testable change when the old code trained or saved custom modules.

1. Run one representative old script with Python warnings enabled.

   $ python -W default embed_legacy.py
   DeprecationWarning: Importing from 'sentence_transformers.models'
   is deprecated and will be removed in a future version.
   The `tokenizer_kwargs` argument was renamed and is now deprecated.
   Please use `processor_kwargs` instead.
   FutureWarning: The `get_sentence_embedding_dimension` method has
   been renamed to `get_embedding_dimension`.
   The `sentences` argument was renamed and is now deprecated.
   Please use `inputs` instead.
   Legacy dimension: 384
   Legacy encode shape: (1, 384)

   The warning run identifies the compatibility calls that need code changes. Warnings from model downloads, authentication, or progress bars are environment noise, not migration findings.

2. Replace deprecated internal module imports with the current module path.

   import sentence_transformers
   from sentence_transformers import SentenceTransformer
    
   modules = sentence_transformers.sentence_transformer.modules
   Transformer = modules.Transformer
   Pooling = modules.Pooling

   Top-level imports such as SentenceTransformer and CrossEncoder stay at the package root. Move older internal imports from the legacy models module only when the project imports modules, losses, evaluators, or custom building blocks directly.

3. Replace renamed constructor and property calls.

   MODEL_NAME = (
       "sentence-transformers/"
       "all-MiniLM-L6-v2"
   )
    
   model = SentenceTransformer(
       MODEL_NAME,
       processor_kwargs={"model_max_length": 128},
   )
    
   print("Dimension:", model.get_embedding_dimension())
   print("Max sequence length:", model.max_seq_length)

   Use processor_kwargs instead of tokenizer_kwargs and max_seq_length instead of older max-length helpers when the code reads or sets sequence length.

4. Replace older encode call shapes with current v5 encoding calls.

   query_embedding = model.encode_query(
       ["How do I migrate code?"]
   )
   document_embeddings = model.encode_document(
       [
           (
               "Use processor_kwargs "
               "instead of tokenizer_kwargs."
           ),
           "Use encode_query.",
       ]
   )
   truncated_embeddings = model.encode(
       inputs=[
           (
               "Sentence Transformers "
               "v5 migration check"
           )
       ],
       truncate_dim=128,
   )

   encode_query() and encode_document() select the query or document task for prompt-aware and Router-based retrieval models. Plain symmetric embedding code can keep using encode() with inputs=.
   Related: How to encode queries and documents with Sentence Transformers
   Related: How to encode embeddings with multiple processes in Sentence Transformers

5. Save a temporary migration smoke test beside the migrated code.

   migration_check.py

   import sentence_transformers
   from sentence_transformers import SentenceTransformer
    
   modules = sentence_transformers.sentence_transformer.modules
   Transformer = modules.Transformer
   Pooling = modules.Pooling
    
   MODEL_NAME = (
       "sentence-transformers/"
       "all-MiniLM-L6-v2"
   )
    
   model = SentenceTransformer(
       MODEL_NAME,
       processor_kwargs={"model_max_length": 128},
   )
    
   query_embedding = model.encode_query(
       ["How do I migrate code?"]
   )
   document_embeddings = model.encode_document(
       [
           (
               "Use processor_kwargs "
               "instead of tokenizer_kwargs."
           ),
           "Use encode_query.",
       ]
   )
   truncated_embeddings = model.encode(
       inputs=[
           (
               "Sentence Transformers "
               "v5 migration check"
           )
       ],
       truncate_dim=128,
   )
    
   print("Dimension:", model.get_embedding_dimension())
   print("Max sequence length:", model.max_seq_length)
   print("Query shape:", query_embedding.shape)
   print("Document shape:", document_embeddings.shape)
   print("Truncated shape:", truncated_embeddings.shape)
   print("Imported modules:", Transformer.__name__, Pooling.__name__)

   Replace the public model and sample strings with one model path and one code path from the project when validating a production migration.

6. Run the smoke test with warnings treated as errors.

   $ python -W error migration_check.py
   Dimension: 384
   Max sequence length: 128
   Query shape: (1, 384)
   Document shape: (2, 384)
   Truncated shape: (1, 128)
   Imported modules: Transformer Pooling

   The command should fail if the migrated file still imports a deprecated compatibility path or calls a renamed v5 API.

7. Remove the temporary smoke-test file.

   $ rm migration_check.py

   Keep a project test that loads the migrated model and exercises the application embedding path if the code is part of a search service, RAG pipeline, or scheduled indexing job.