Install & Compatibility
Where this runs
tested against v6.0.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.10
✕ build_error
1/5 runs
py 3.11
✕ build_error
✕ timeout
py 3.12
✕ build_error
✕ timeout
py 3.13
✕ build_error
4/5 runs
py 3.9
✕ build_error
✕ timeout
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
SentenceTransformer
✓ from sentence_transformers import SentenceTransformer
✗ import sentence-transformers
Hyphen in package name, underscore in import. The most common install/import confusion for new users.
CrossEncoder
✓ from sentence_transformers import CrossEncoder
For reranking. CrossEncoder scores pairs (query, doc) — not suitable for encoding corpora. Use SentenceTransformer for that.
util.cos_sim
✓ from sentence_transformers import util
util.cos_sim(), util.dot_score(), util.semantic_search() are built-in similarity utilities.
encode() returns float32 numpy arrays by default. Pass convert_to_tensor=True for PyTorch tensors. Models are cached in HF_HOME after first download. all-MiniLM-L6-v2 is 384-dim, fast, and good for general use.
from sentence_transformers import SentenceTransformer, util
import numpy as np
# Load model (downloads on first use, ~90MB for MiniLM)
model = SentenceTransformer("all-MiniLM-L6-v2")
# Encode sentences → numpy float32 arrays by default
sentences = [
"The cat sat on the mat.",
"A feline rested on a rug.",
"The stock market crashed today."
]
embeddings = model.encode(sentences) # shape: (3, 384)
print(embeddings.shape)
# Cosine similarity
cosine_scores = util.cos_sim(embeddings[0], embeddings[1:])
print(cosine_scores) # similar pair scores higher
# Return torch tensors instead of numpy
embeddings_tensor = model.encode(sentences, convert_to_tensor=True)
# Semantic search
query_embedding = model.encode("Where did the cat sleep?", convert_to_tensor=True)
hits = util.semantic_search(query_embedding, embeddings_tensor, top_k=2)
print(hits)
Debug
Known issues
breakingPython 3.10+ required as of sentence-transformers 5.0. Python 3.9 and below will fail to install.fixUpgrade to Python 3.10+. For Python 3.9, pin: pip install sentence-transformers<5.
affects: >=5.0.0
breakingsentence-transformers 5.2.2+ dropped the requests dependency in favor of optional httpx, aligning with transformers v5. Code that relied on requests being transitively installed via sentence-transformers may see ImportError on requests.fixIf your code uses requests directly, add it explicitly: pip install requests.
affects: >=5.2.2
breakingTraining with sentence-transformers 5.x requires pinning to a compatible transformers version. sentence-transformers 5.2.3 introduced a compatibility fix for transformers v5.2 Trainer changes. Older sentence-transformers 5.x with transformers v5.2 causes training failures at the logging step.fixUpgrade to sentence-transformers>=5.2.3 when using transformers>=5.2.
affects: sentence-transformers 5.0-5.2.2 with transformers 5.2
gotchaencode() returns numpy float32 arrays by default, not torch tensors. Passing embeddings directly to PyTorch operations without converting first causes TypeError. Many tutorials omit this.fixUse convert_to_tensor=True to get torch.Tensor, or call torch.tensor(embeddings) manually.
affects: all
gotchaCrossEncoder and SentenceTransformer are architecturally different and not interchangeable. CrossEncoder scores (query, doc) pairs — it cannot encode a corpus of documents independently. Using CrossEncoder where SentenceTransformer is needed produces wrong results with no error.fixUse SentenceTransformer for bi-encoder embedding (fast, scalable). Use CrossEncoder for reranking a small candidate set (slow, higher accuracy).
affects: all
gotchautil.cos_sim() returns values in [-1, 1]. It does NOT return [0, 1]. Thresholding at 0.5 as a "similarity cutoff" is a common mistake — the actual meaningful threshold depends on the model and task.fixCalibrate thresholds empirically for your specific model and domain. For all-MiniLM-L6-v2, 0.3+ is often a reasonable rough threshold for semantic similarity.
affects: all
gotchaPackage name is sentence-transformers (hyphen) but import name is sentence_transformers (underscore). import sentence-transformers raises SyntaxError. from sentence-transformers import ... also fails.fixpip install sentence-transformers (hyphen). from sentence_transformers import SentenceTransformer (underscore).
affects: all
breakingInstallation of sentence-transformers will fail because its core dependency, PyTorch (torch), currently lacks official binary wheels for Python 3.13, especially on Alpine Linux. PyTorch wheels are often not released for the newest Python versions immediately and may not support musl libc distributions.fixUse a Python version for which PyTorch wheels are readily available (e.g., Python 3.10-3.12). Consider using a glibc-based Linux distribution (like Debian or Ubuntu) instead of Alpine if pre-built PyTorch wheels are required, or attempt to build PyTorch from source (a complex and time-consuming process).
affects: all
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'sentence_transformers'
The `sentence-transformers` package is not installed in the current Python environment.
fixpip install sentence-transformers
TypeError: 'str' object cannot be interpreted as an integer
The `model.encode()` method was provided with a single string instead of an expected list of strings.
fixWrap the single input string in a list, e.g., `model.encode(["your single sentence here"])`.
RuntimeError: CUDA out of memory. Tried to allocate X GiB (GPU X; X GiB total capacity; X GiB already allocated; X GiB free; X GiB reserved in total by PyTorch)
The GPU does not have enough memory to process the current batch size or model, or other processes are consuming GPU memory.
fixReduce the `batch_size` parameter in `model.encode()`, use a smaller model, or explicitly move the model to CPU (`model.to('cpu')`). OSError: Can't load tokenizer for 'model-name'. If you were trying to load a tokenizer from a checkpoint saved by `save_pretrained`, make sure that 'model-name' is the path to a directory containing files saved by `save_pretrained`.
The specified model name is incorrect, unavailable on Hugging Face Hub, or a network issue prevented its download.
fixVerify the model name for typos, ensure a stable internet connection, or try a different, well-known model from the Hugging Face Hub.
Upgrade
Version history
6.0.0latest on PyPI · released Aug 18, 2026
Audit
Dependencies
transformersrequiredRequired. sentence-transformers wraps HF transformers for model loading and tokenization.
torchrequiredRequired. PyTorch is the default compute backend.
huggingface-hubrequiredRequired. Used for model download and Hub interactions.
numpyrequiredRequired. encode() returns numpy arrays by default.