Install & Compatibility
Where this runs
tested against v0.8.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
muslpy 3.10–3.910 runs
build_error
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 11.3s · import 1.902s · 266MB
240MB installed
● package 240MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
TextEmbedding
✓ from fastembed import TextEmbedding
SparseEmbedding
✓ from fastembed import SparseEmbedding
Reranker
✓ from fastembed import Reranker
LateInteractionTextEmbedding
✓ from fastembed.late_interaction.late_interaction_text_embedding import LateInteractionTextEmbedding
For late interaction models like ColBERT.
This quickstart demonstrates how to initialize a `TextEmbedding` model, download it if necessary, and then generate embeddings for a list of documents. It uses the `BAAI/bge-small-en-v1.5` model as an example.
from fastembed import TextEmbedding
# Initialize the embedding model. Model will be downloaded if not cached.
# Pass specific_model_path for local models, or use local_files_only=True
model = TextEmbedding(model_name="BAAI/bge-small-en-v1.5")
documents = [
"This is a document about the weather in London. It's quite rainy.",
"The quick brown fox jumps over the lazy dog.",
"Python is a high-level, interpreted programming language."
]
# Embed the documents
embeddings = model.embed(documents)
print(f"Generated {len(embeddings)} embeddings.")
print(f"First embedding shape: {embeddings[0].shape}")
print(f"First embedding (first 5 values): {embeddings[0][:5]}")
Debug
Known issues
breakingPython 3.9 is no longer supported starting from v0.8.0. Previously, Python 3.8 was dropped in v0.5.0. Ensure your environment uses Python 3.10 or newer.fixUpgrade your Python environment to 3.10, 3.11, or 3.12.
affects: >=0.8.0
gotchaFastEmbed v0.8.0+ automatically utilizes CUDA if a compatible GPU is detected and `onnxruntime-gpu` is installed. Explicitly setting `cuda=True` is no longer required and may not be honored if the environment is not set up correctly.fixEnsure `onnxruntime-gpu` is installed for GPU usage. Remove `cuda=True` from `TextEmbedding` initialization if it causes issues; auto-detection is now the default behavior.
affects: >=0.8.0
gotchaSpecific versions of `onnxruntime` and `pillow` were fixed in v0.8.0, especially for Python 3.14 compatibility and security. Users on Python 3.14 or those with older transitive dependencies might encounter installation or runtime issues.fixAlways install the latest `fastembed` version to get the most compatible `onnxruntime` and `pillow` versions. If installing on Python 3.14, ensure `fastembed >= 0.8.0`.
affects: All versions, especially older <0.8.0
gotchaWhile `local_files_only=True` prevents downloads, earlier versions (before v0.7.4) might have still made network calls if the model wasn't cached. As of v0.8.0, the `HF_HUB_OFFLINE` environment variable is also respected, providing a more robust offline experience.fixFor strictly offline scenarios, ensure models are pre-cached and set `HF_HUB_OFFLINE=1` in your environment, in addition to using `local_files_only=True`.
affects: <0.8.0
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'fastembed'
The 'fastembed' library is not installed in your Python environment or the environment where you are running your code.
fixInstall the library using pip: `pip install fastembed`
AttributeError: module 'fastembed' has no attribute 'TextEmbedding'
You are attempting to import 'TextEmbedding' or another core class from the top-level 'fastembed' module, but it might be defined in a submodule or the import statement has incorrect casing. In current versions, it's typically directly importable from `fastembed`.
fixEnsure you are using the correct import statement as shown in the official documentation, typically `from fastembed import TextEmbedding` or `from fastembed import SparseTextEmbedding`. If this still fails, verify your `fastembed` version is up-to-date.
AttributeError: 'FastEmbedEmbeddings' object has no attribute '_model'
This error often occurs when integrating `fastembed` with other libraries (like Langchain) and there's a version incompatibility, particularly with `pydantic`. The internal `_model` attribute might not be initialized correctly due to issues with the wrapper class's configuration or conflicting `pydantic` versions.
fixDowngrade `pydantic` to a version compatible with your `fastembed` (e.g., `pip install "pydantic<2.0"`), or ensure that `fastembed` is installed in a fresh virtual environment allowing it to manage its own dependencies. Avoid modifying internal attributes directly if possible.
onnxruntime.capi.onnxruntime_pybind11_state.Fail: [ONNXRuntimeError]
This is a general ONNX Runtime error indicating an issue with the underlying ONNX execution environment. Common causes include incompatible ONNX Runtime versions, missing shared libraries, or environmental setup problems (e.g., conflicting CPU/GPU ONNX Runtime installations).
fixCheck for `onnxruntime` version compatibility with `fastembed`. Ensure the correct ONNX Runtime package (CPU or GPU) is installed and that there are no conflicts. For Windows, verify `onnxruntime.dll` is correctly located. For Linux/macOS, ensure shared libraries like `libonnxruntime.so` are discoverable. Try reinstalling `fastembed` and `onnxruntime` in a clean environment.
Could not download model from HuggingFace: Repo id must be in the form 'repo_name' or 'namespace/repo_name'
The model name provided for download is not in the expected Hugging Face repository ID format. This can also occur due to network issues, rate limiting, or if a required `HF_TOKEN` for private models is missing or invalid.
fixEnsure the model name is correctly formatted (e.g., 'BAAI/bge-small-en-v1.5' instead of a full URL). Check your internet connection. If accessing a private model or encountering rate limits, set your Hugging Face API token in the environment variable `HF_TOKEN` or pass it explicitly if the API allows. You can also specify a `cache_dir` to manage model storage.
Upgrade
Version history
0.8.0latest on PyPI · released Mar 23, 2026
Audit
Dependencies
onnxruntimerequiredCore dependency for model inference, ensures high performance.
onnxruntime-gpuoptionalRequired for GPU acceleration, specified via `fastembed[gpu]`.