{"id":73,"library":"sentence-transformers","title":"Sentence Transformers","description":"Framework for computing dense sentence/text/image embeddings using transformer models. Primary use cases: semantic search, semantic similarity, clustering, and reranking. Wraps transformers and provides SentenceTransformer (embedding), CrossEncoder (reranker), and SparseEncoder (sparse embedding) classes. 15,000+ pretrained models on HF Hub. Now officially maintained by Hugging Face (Tom Aarsen) after transfer from UKP Lab/TU Darmstadt. Package name: sentence-transformers (hyphen). Import name: sentence_transformers (underscore).","status":"active","version":"5.3.0","language":"python","source_language":"en","source_url":"https://github.com/UKPLab/sentence-transformers","tags":["sentence-transformers","embeddings","semantic-search","sbert","cosine-similarity","reranking","cross-encoder","rag","huggingface"],"install":[{"cmd":"pip install sentence-transformers","lang":"bash","label":"Core (inference only)"},{"cmd":"pip install sentence-transformers[train]","lang":"bash","label":"With training dependencies"},{"cmd":"pip install sentence-transformers[onnx]","lang":"bash","label":"With ONNX backend (CPU inference optimization)"},{"cmd":"pip install sentence-transformers[onnx-gpu]","lang":"bash","label":"With ONNX GPU backend"},{"cmd":"pip install sentence-transformers[openvino]","lang":"bash","label":"With OpenVINO backend (Intel)"}],"dependencies":[{"reason":"Required. sentence-transformers wraps HF transformers for model loading and tokenization.","package":"transformers","optional":false},{"reason":"Required. PyTorch is the default compute backend.","package":"torch","optional":false},{"reason":"Required. Used for model download and Hub interactions.","package":"huggingface-hub","optional":false},{"reason":"Required. encode() returns numpy arrays by default.","package":"numpy","optional":false}],"imports":[{"note":"Hyphen in package name, underscore in import. The most common install/import confusion for new users.","wrong":"import sentence-transformers","symbol":"SentenceTransformer","correct":"from sentence_transformers import SentenceTransformer"},{"note":"For reranking. CrossEncoder scores pairs (query, doc) — not suitable for encoding corpora. Use SentenceTransformer for that.","symbol":"CrossEncoder","correct":"from sentence_transformers import CrossEncoder"},{"note":"util.cos_sim(), util.dot_score(), util.semantic_search() are built-in similarity utilities.","symbol":"util.cos_sim","correct":"from sentence_transformers import util"}],"quickstart":{"code":"from sentence_transformers import SentenceTransformer, util\nimport numpy as np\n\n# Load model (downloads on first use, ~90MB for MiniLM)\nmodel = SentenceTransformer(\"all-MiniLM-L6-v2\")\n\n# Encode sentences → numpy float32 arrays by default\nsentences = [\n    \"The cat sat on the mat.\",\n    \"A feline rested on a rug.\",\n    \"The stock market crashed today.\"\n]\nembeddings = model.encode(sentences)  # shape: (3, 384)\nprint(embeddings.shape)\n\n# Cosine similarity\ncosine_scores = util.cos_sim(embeddings[0], embeddings[1:])\nprint(cosine_scores)  # similar pair scores higher\n\n# Return torch tensors instead of numpy\nembeddings_tensor = model.encode(sentences, convert_to_tensor=True)\n\n# Semantic search\nquery_embedding = model.encode(\"Where did the cat sleep?\", convert_to_tensor=True)\nhits = util.semantic_search(query_embedding, embeddings_tensor, top_k=2)\nprint(hits)","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade to Python 3.10+. For Python 3.9, pin: pip install sentence-transformers<5.","message":"Python 3.10+ required as of sentence-transformers 5.0. Python 3.9 and below will fail to install.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"If your code uses requests directly, add it explicitly: pip install requests.","message":"sentence-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.","severity":"breaking","affected_versions":">=5.2.2"},{"fix":"Upgrade to sentence-transformers>=5.2.3 when using transformers>=5.2.","message":"Training 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.","severity":"breaking","affected_versions":"sentence-transformers 5.0-5.2.2 with transformers 5.2"},{"fix":"Use convert_to_tensor=True to get torch.Tensor, or call torch.tensor(embeddings) manually.","message":"encode() returns numpy float32 arrays by default, not torch tensors. Passing embeddings directly to PyTorch operations without converting first causes TypeError. Many tutorials omit this.","severity":"gotcha","affected_versions":"all"},{"fix":"Use SentenceTransformer for bi-encoder embedding (fast, scalable). Use CrossEncoder for reranking a small candidate set (slow, higher accuracy).","message":"CrossEncoder 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.","severity":"gotcha","affected_versions":"all"},{"fix":"Calibrate thresholds empirically for your specific model and domain. For all-MiniLM-L6-v2, 0.3+ is often a reasonable rough threshold for semantic similarity.","message":"util.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.","severity":"gotcha","affected_versions":"all"},{"fix":"pip install sentence-transformers (hyphen). from sentence_transformers import SentenceTransformer (underscore).","message":"Package name is sentence-transformers (hyphen) but import name is sentence_transformers (underscore). import sentence-transformers raises SyntaxError. from sentence-transformers import ... also fails.","severity":"gotcha","affected_versions":"all"},{"fix":"Use 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).","message":"Installation 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.","severity":"breaking","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-05-12T07:25:51.877Z","next_check":"2026-06-17T00:00:00.000Z","problems":[{"fix":"pip install sentence-transformers","cause":"The `sentence-transformers` package is not installed in the current Python environment.","error":"ModuleNotFoundError: No module named 'sentence_transformers'"},{"fix":"Wrap the single input string in a list, e.g., `model.encode([\"your single sentence here\"])`.","cause":"The `model.encode()` method was provided with a single string instead of an expected list of strings.","error":"TypeError: 'str' object cannot be interpreted as an integer"},{"fix":"Reduce the `batch_size` parameter in `model.encode()`, use a smaller model, or explicitly move the model to CPU (`model.to('cpu')`).","cause":"The GPU does not have enough memory to process the current batch size or model, or other processes are consuming GPU memory.","error":"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)"},{"fix":"Verify the model name for typos, ensure a stable internet connection, or try a different, well-known model from the Hugging Face Hub.","cause":"The specified model name is incorrect, unavailable on Hugging Face Hub, or a network issue prevented its download.","error":"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`."}],"ecosystem":"pypi","meta_description":null,"install_score":0,"install_tag":"stale","quickstart_score":0,"quickstart_tag":"stale","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"onnx-gpu","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"onnx","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"openvino","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"train","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":18.51,"mem_mb":178,"disk_size":"4.9G"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"onnx-gpu","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"onnx","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"openvino","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"train","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"onnx-gpu","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"onnx","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"openvino","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"train","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":23.47,"mem_mb":203.7,"disk_size":"5.0G"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"onnx-gpu","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"onnx","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":23.53,"mem_mb":197.5,"disk_size":"5.2G"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"openvino","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":24.28,"mem_mb":201.5,"disk_size":"5.3G"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"train","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"onnx-gpu","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"onnx","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"openvino","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"train","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":24.68,"mem_mb":197.3,"disk_size":"5.0G"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"onnx-gpu","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":24.66,"mem_mb":191.3,"disk_size":"5.5G"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"onnx","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":24.27,"mem_mb":191.3,"disk_size":"5.2G"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"openvino","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":24.54,"mem_mb":195.1,"disk_size":"5.3G"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"train","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"onnx-gpu","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"onnx","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"openvino","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"train","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":21.36,"mem_mb":201.7,"disk_size":"5.0G"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"onnx-gpu","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":21.06,"mem_mb":195.8,"disk_size":"5.5G"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"onnx","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":20.75,"mem_mb":195.8,"disk_size":"5.2G"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"openvino","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":20.81,"mem_mb":199.6,"disk_size":"5.3G"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"train","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":25.69,"mem_mb":242.8,"disk_size":"5.3G"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"onnx-gpu","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"onnx","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"openvino","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"train","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"onnx-gpu","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"onnx","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"openvino","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"train","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null}]},"quickstart_checks":{"last_tested":"2026-05-12","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":-1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":-1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":-1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":-1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":-1}]}}