Guide · Open source

How to use turbovec: install, index and search vectors

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

turbovec is an in-process vector index for Python and Rust that stores embedding vectors in a compressed form at 2 or 4 bits per dimension and finds the closest matches to a query. This guide is for developers building semantic search or retrieval-augmented generation (RAG) who want a local store that runs inside their program. After reading it you will be able to install turbovec, build and search an index, save and reload it, and decide whether it fits your project.

turbovecRyanCodrai/turbovec · ★ 17.5k · MIT Install options & downloads

Quick start

1Install the package. Run pip install turbovec for Python or cargo add turbovec for Rust. Make sure NumPy is available for Python.
2Load your embeddings. Load your vectors as a 2-D float32 array with shape (n, dim). Normalise them if you want cosine similarity.
3Create the index. Create a TurboQuantIndex with your dimension and a bit width of 2 or 4.
4Add vectors and search. Call add with your array, then call search with a query and k to get scores and slot indices.
5Save with sync. Call sync with a file path. Later calls write only the changes.
6Reload when needed. Call TurboQuantIndex.load with the file path to restore the index.

Install turbovec in Python or Rust

turbovec is distributed through package managers. For Python, install it from PyPI. The Python usage also needs NumPy, because inputs are NumPy arrays. The README excerpt does not state a minimum Python version.

For Rust, add the crate with Cargo. The crate is named turbovec on crates.io.

Python: a working Python environment with NumPy installed
Rust: Cargo, to add the crate to your project

pip install turbovec

cargo add turbovec

Create an index and add vectors

Create a TurboQuantIndex with the dimension of your embeddings and a bit width of 2 or 4. Inputs must be 2-D float32 arrays of shape (n, dim). Other dtypes raise an error rather than being converted silently, so cast your array to float32 first.

Scores returned by search are inner products. If you want cosine similarity, normalise your vectors before adding them.

dim must be a multiple of 8 and no more than 16,384
bit_width is 2 or 4
Use float32 arrays of shape (n, dim)

import numpy as np
from turbovec import TurboQuantIndex

vectors = np.load("embeddings.npy").astype(np.float32)   # shape (n, 1536)

index = TurboQuantIndex(dim=1536, bit_width=4)
index.add(vectors)

Search for the nearest vectors

Call search with a query array and the number of results k. The result is two arrays: scores, which are float32 inner products, and indices, which are int64 slot positions in the index.

Search scans every stored vector, so cost grows with the size of the corpus.

scores, indices = index.search(vectors[:1], k=5)
print(indices)         # int64 slot positions
print(scores.shape)    # (1, 5)

Save, sync and reload the index

The sync method writes only what changed since the last call, using one fsync. The first sync writes the file. Later syncs write just the change. To reload, call TurboQuantIndex.load, which accepts a file written by either sync or write.

The Rust API offers write and load for the same purpose.

index.sync("index.tv")                  # first sync writes the file
index.add(more_vectors)
index.sync("index.tv")                  # later syncs write just the change, durably

index = TurboQuantIndex.load("index.tv")   # loads either a sync'd or a write() file

Use your own ids and filters with IdMapIndex

If you need ids that survive deletes, use IdMapIndex. It keys every vector by your own uint64 id. Removing an id is an O(1) operation according to the README.

search accepts an allowlist of ids, so you can restrict results to ids approved by another system such as a SQL predicate, an access control list or a time window. The filter returns up to k results from the allowed set.

add_with_ids takes a uint64 id array, one id per row
remove(id) deletes one vector by its id
allowlist limits search to the ids you pass

from turbovec import IdMapIndex

index = IdMapIndex(dim=1536, bit_width=4)
index.add_with_ids(vectors, ids)

scores, ids = index.search(query, k=10)
index.remove(1002)

allowed = np.array([1001, 1003, 1042], dtype=np.uint64)
scores, ids = index.search(query, k=10, allowlist=allowed)

Check whether turbovec fits your workload

turbovec is a library, not a server. It has no network API, replication or multi-tenant service. The README says it scans every vector and suggests an HNSW or IVF index in front of it for hundreds of millions of vectors with strict latency needs.

Quantization is lossy, so recall depends on your data. The README recommends checking recall on a sample of your own data. Framework integrations exist for LangChain, LlamaIndex, Haystack and Agno, installed as extras such as pip install turbovec[langchain].

Good fit: local semantic search or RAG over a few million or fewer embeddings on one machine
Poor fit: hosted or networked vector databases, or exact float results

What people use it for

Semantic search over a few million or fewer embeddings on a single machine
A local, offline vector store for a RAG pipeline
Keeping embedding memory use low by storing vectors at 2 or 4 bits per dimension
Apps that frequently add and remove vectors, using IdMapIndex with remove
Adding a drop-in store to a project already using LangChain, LlamaIndex, Haystack or Agno

Frequently asked questions

Is turbovec free to use?

turbovec is released under the MIT licence, according to the project's licence badge and metadata. You can check the LICENSE file in the repository for the full terms.

How do I install turbovec?

For Python, run pip install turbovec, and install NumPy as well. For Rust, run cargo add turbovec. The README does not state a minimum Python version.

What do I need to run turbovec?

You need Python with NumPy, or Rust with Cargo. Inputs must be 2-D float32 arrays, and vector dimensions must be a multiple of 8 and no more than 16,384.

Is turbovec faster than FAISS?

The README reports benchmarks in which turbovec searched faster than FAISS IndexPQFastScan at matched bit rates, for example 4.0× on ARM at 4-bit. These are the project's own results on specific OpenAI and GloVe datasets, so test on your own data.

Does turbovec need a server?

No. turbovec runs as a library inside your program and stores its data in a file. It has no network API, replication or multi-tenant service.

What are good alternatives to turbovec?

The README names FAISS, HNSW (hnswlib), Chroma and Qdrant as comparable projects. Choose HNSW or an IVF index for very large corpora with strict latency needs, and a server-based database if you need networking or multi-tenancy.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

turbovec suits Python or Rust developers who want a local, offline, memory-efficient vector store for a few million or fewer embeddings on one machine. If you need hundreds of millions of vectors with strict latency, exact float results, or a hosted network database, pick an HNSW or IVF index, or a server-based vector database instead.

Install options & downloads