# What changed in fastembed

> 62 changes in fastembed 0.8 to 0.9 from its official release notes, upgrade guides and advisories: 16 breaking, 1 security, 23 new APIs and options. Each one cited. Sources checked 2026-10-28. HTML: https://unstale.sh/pypi/fastembed/

To see which of these apply to a repository, run `npx @unstale/cli init` in it.

## fastembed 0.9

### Breaking changes

- Rejects custom cross-encoder names that differ from a registered name only by case, preventing them from silently resolving to the earlier model. (0.9.1) — [release notes](https://github.com/qdrant/fastembed/releases/tag/v0.9.1)
- Raises a ValueError when a custom model with disabled pooling returns per-token output instead of sentence embeddings. (0.9.1) — [release notes](https://github.com/qdrant/fastembed/releases/tag/v0.9.1)
- Values below 1 now raise a ValueError. (0.9.0) — [release notes](https://github.com/qdrant/fastembed/releases/tag/v0.9.0)
- Image preprocessing now matches Jina's center crop; image embeddings change for some image sizes. (0.9.0) — [release notes](https://github.com/qdrant/fastembed/releases/tag/v0.9.0)
- The default batch_size changes from 16 to 2, including for Qdrant/colpali-v1.3-fp16. (0.9.0) — [release notes](https://github.com/qdrant/fastembed/releases/tag/v0.9.0)
- Embeddings are now returned as float32 instead of float64. (0.9.0) — [release notes](https://github.com/qdrant/fastembed/releases/tag/v0.9.0)
- Built-in models now download only from Hugging Face, without the GCS fallback; custom models still support url and hf sources. (0.9.0) — [release notes](https://github.com/qdrant/fastembed/releases/tag/v0.9.0)
- Encoding an empty multivector now raises a ValueError. (0.9.0) — [release notes](https://github.com/qdrant/fastembed/releases/tag/v0.9.0)
- Qdrant/colmodernvbert now requires onnxruntime>=1.19. (0.9.0) — [release notes](https://github.com/qdrant/fastembed/releases/tag/v0.9.0)
- The stray 128-token limit is removed and the limit is now 512 tokens on a fresh download; embeddings of longer texts change. (0.9.0) — [release notes](https://github.com/qdrant/fastembed/releases/tag/v0.9.0)
- The stray 128-token limit is removed and the limit is now 256 tokens on a fresh download; embeddings of longer texts change. (0.9.0) — [release notes](https://github.com/qdrant/fastembed/releases/tag/v0.9.0)
- Now loads model_v2.onnx and drops padding rows from embeddings; offline setups need to download it first, and affected image embeddings should be re-embedded. (0.9.0) — [release notes](https://github.com/qdrant/fastembed/releases/tag/v0.9.0)
- The stray 128-token limit is removed and the limit is now 256 tokens on a fresh download; embeddings of longer texts change. (0.9.0) — [release notes](https://github.com/qdrant/fastembed/releases/tag/v0.9.0)
- The stray 128-token limit is removed and the limit is now 512 tokens on a fresh download; embeddings of longer texts change. (0.9.0) — [release notes](https://github.com/qdrant/fastembed/releases/tag/v0.9.0)

### New APIs and options

- Adds an option to memory-map the potion models' embedding matrix, enabling instant loading and sharing one copy among parallel workers. (0.9.1) — [release notes](https://github.com/qdrant/fastembed/releases/tag/v0.9.1)
- Added this reranker model for use with fastembed. (0.9.0) — [release notes](https://github.com/qdrant/fastembed/releases/tag/v0.9.0)
- Added the int8 version of this reranker model for use with fastembed. (0.9.0) — [release notes](https://github.com/qdrant/fastembed/releases/tag/v0.9.0)
- Added this model for use with fastembed. (0.9.0) — [release notes](https://github.com/qdrant/fastembed/releases/tag/v0.9.0)
- Added this model for use with fastembed. (0.9.0) — [release notes](https://github.com/qdrant/fastembed/releases/tag/v0.9.0)
- Added this multilingual model for use with fastembed. (0.9.0) — [release notes](https://github.com/qdrant/fastembed/releases/tag/v0.9.0)
- Added the stemmer parameter to support languages without a Snowball stemmer, such as Polish. (0.9.0) — [release notes](https://github.com/qdrant/fastembed/releases/tag/v0.9.0)
- Added the stopwords parameter to support languages without a Snowball stemmer, such as Polish. (0.9.0) — [release notes](https://github.com/qdrant/fastembed/releases/tag/v0.9.0)
- Added this small query encoder for searching embeddings from Qdrant/stella-en-400M-v5-doc-onnx. (0.9.0) — [release notes](https://github.com/qdrant/fastembed/releases/tag/v0.9.0)
- Added this small query encoder for searching embeddings from Qdrant/stella-en-400M-v5-doc-onnx. (0.9.0) — [release notes](https://github.com/qdrant/fastembed/releases/tag/v0.9.0)
- Added this document encoder for use with fastembed. (0.9.0) — [release notes](https://github.com/qdrant/fastembed/releases/tag/v0.9.0)
- Added output_name to select which ONNX output a custom model uses. (0.9.0) — [release notes](https://github.com/qdrant/fastembed/releases/tag/v0.9.0)

### Performance

- Potion models run with numpy instead of ONNX, producing unchanged outputs and running 1.9x to 2.6x faster on documents. (0.9.1) — [release notes](https://github.com/qdrant/fastembed/releases/tag/v0.9.1)
- Embedding a single text, such as a query, is faster with the potion models. (0.9.1) — [release notes](https://github.com/qdrant/fastembed/releases/tag/v0.9.1)
- Document encoding is faster for large k_sim values. (0.9.0) — [release notes](https://github.com/qdrant/fastembed/releases/tag/v0.9.0)

### Behavior and default changes

- Nearest-neighbor interpolation is now accepted in image preprocessing. (0.9.0) — [release notes](https://github.com/qdrant/fastembed/releases/tag/v0.9.0)
- With lazy_load=True, token_count() loads only the tokenizer instead of the ONNX model. (0.9.0) — [release notes](https://github.com/qdrant/fastembed/releases/tag/v0.9.0)

### Fixes and other changes

- Allows Pillow 13. (0.9.1) — [release notes](https://github.com/qdrant/fastembed/releases/tag/v0.9.1)
- parallel workers now respect cuda=False when onnxruntime-gpu is installed. (0.9.0) — [release notes](https://github.com/qdrant/fastembed/releases/tag/v0.9.0)
- ConvNeXT image preprocessing now respects do_resize=False. (0.9.0) — [release notes](https://github.com/qdrant/fastembed/releases/tag/v0.9.0)
- Fixed token ID overflow in query embeddings. (0.9.0) — [release notes](https://github.com/qdrant/fastembed/releases/tag/v0.9.0)
- Empty dictionaries now produce int64 indices. (0.9.0) — [release notes](https://github.com/qdrant/fastembed/releases/tag/v0.9.0)
- Very small weights are preserved by computing them with log1p. (0.9.0) — [release notes](https://github.com/qdrant/fastembed/releases/tag/v0.9.0)
- Tokenization now honors the truncation and padding side specified in the model's tokenizer config. (0.9.0) — [release notes](https://github.com/qdrant/fastembed/releases/tag/v0.9.0)

## fastembed 0.8

### Breaking changes

- Now resolves to Qdrant/bge-base-en-v1.5-onnx-Q; its cache directory casing changes, so existing caches may not be reused and offline setups must refresh the cache before upgrading. (0.8.1) — [release notes](https://github.com/qdrant/fastembed/releases/tag/v0.8.1)
- The default model now resolves to Qdrant/bge-small-en-v1.5-onnx-Q; its cache directory casing changes, so existing caches may not be reused and offline setups must refresh the cache before upgrading. (0.8.1) — [release notes](https://github.com/qdrant/fastembed/releases/tag/v0.8.1)

### Security

- Fixed a path traversal vulnerability that could write files outside the cache directory. (0.8.1) — [release notes](https://github.com/qdrant/fastembed/releases/tag/v0.8.1)

### New APIs and options

- Added this model for use with fastembed. (0.8.1) — [release notes](https://github.com/qdrant/fastembed/releases/tag/v0.8.1)
- Added this model to TextEmbedding and ImageEmbedding. (0.8.1) — [release notes](https://github.com/qdrant/fastembed/releases/tag/v0.8.1)
- Added this Model2Vec static model. (0.8.1) — [release notes](https://github.com/qdrant/fastembed/releases/tag/v0.8.1)
- Added this Model2Vec static model. (0.8.1) — [release notes](https://github.com/qdrant/fastembed/releases/tag/v0.8.1)
- Added this Model2Vec static model. (0.8.1) — [release notes](https://github.com/qdrant/fastembed/releases/tag/v0.8.1)
- Added this vision model; it shares an embedding space with the text model for text-to-image search. (0.8.1) — [release notes](https://github.com/qdrant/fastembed/releases/tag/v0.8.1)
- Added this vision model; it shares an embedding space with the text model for text-to-image search. (0.8.1) — [release notes](https://github.com/qdrant/fastembed/releases/tag/v0.8.1)
- Added inference-free SPLADE for documents; queries are encoded without inference. (0.8.1) — [release notes](https://github.com/qdrant/fastembed/releases/tag/v0.8.1)
- Added LAST_TOKEN pooling for custom models. (0.8.1) — [release notes](https://github.com/qdrant/fastembed/releases/tag/v0.8.1)
- Added this embedding model. (0.8.1) — [release notes](https://github.com/qdrant/fastembed/releases/tag/v0.8.1)
- Added this quantized embedding model; it requires onnxruntime>=1.23. (0.8.1) — [release notes](https://github.com/qdrant/fastembed/releases/tag/v0.8.1)

### Behavior and default changes

- Checks that model files exist before using a cached model, allowing variants such as fp32 and quantized models to share a cache directory. (0.8.1) — [release notes](https://github.com/qdrant/fastembed/releases/tag/v0.8.1)
- config.json and special_tokens_map.json are now optional when loading a tokenizer. (0.8.1) — [release notes](https://github.com/qdrant/fastembed/releases/tag/v0.8.1)

### Fixes and other changes

- Custom text embedding and cross-encoder models no longer fail when parallel is set. (0.8.1) — [release notes](https://github.com/qdrant/fastembed/releases/tag/v0.8.1)
- Batches are always padded to their longest sequence, fixing ValueError on mixed-length batches for models whose tokenizer ships a fixed padding length. (0.8.1) — [release notes](https://github.com/qdrant/fastembed/releases/tag/v0.8.1)
- Normalization of batched (N, C, H, W) image arrays now uses the correct axis. (0.8.1) — [release notes](https://github.com/qdrant/fastembed/releases/tag/v0.8.1)
- Loading a custom text model registered with different casing no longer raises KeyError. (0.8.1) — [release notes](https://github.com/qdrant/fastembed/releases/tag/v0.8.1)
- Downloads now have a timeout so a stalled connection fails instead of hanging indefinitely. (0.8.1) — [release notes](https://github.com/qdrant/fastembed/releases/tag/v0.8.1)
- Each download is staged in its own temporary directory so failed or concurrent downloads cannot delete files from other downloads. (0.8.1) — [release notes](https://github.com/qdrant/fastembed/releases/tag/v0.8.1)
- Now runs the fp32 model instead of fp16, which fails on onnxruntime>=1.23; the download grows from 0.32 GB to 0.64 GB. (0.8.1) — [release notes](https://github.com/qdrant/fastembed/releases/tag/v0.8.1)
- Fixed the transform swapping height and width for non-square sizes. (0.8.1) — [release notes](https://github.com/qdrant/fastembed/releases/tag/v0.8.1)