RaBitQ Library

Compact vectors. Accurate distances. Fast ANN search.

A research-backed C++17 library with Python bindings for 1-bit and multi-bit
vector quantization, IVF, HNSW, SymphonyQG, and clustering.

Documentation · Python package · Paper · Releases · Maintenance

News

• October 2026 — v0.5.2: HNSW add, resize, and remove, batch search for IVF and SymphonyQG, and clustering and allocation optimizations.
• September 2026 — Cross-platform support: C++ builds and CPython 3.11–3.14 wheels for Linux x86-64/ARM64, Windows x86-64, and macOS 14+ ARM64.

Install

python -m pip install --upgrade "rabitqlib>=0.5.2"

Wheels cover the platforms above. x86-64 requires AVX2/FMA and optionally uses AVX-512; ARM64 uses NEON. See platform requirements and source installation.

Python quick start

Build and search a small IVF index using synthetic data:

import numpy as np
from rabitqlib import FinalAssignmentMode, IvfIndex, RaBitQKMeans

rng = np.random.default_rng(42)
data = rng.standard_normal((500, 64)).astype(np.float32)
queries = rng.standard_normal((5, 64)).astype(np.float32)

clustering = RaBitQKMeans(
    64, 5, num_threads=2, final_assignment=FinalAssignmentMode.Exact
)
clustering.train(data)

index = IvfIndex(
    dim=64,
    max_elements=len(data),
    num_clusters=5,
    nbits=4,
    metric="l2",
)
index.build(data, clustering.centroids, clustering.assignments)

ids, distances = index.search(queries, k=10, nprobe=5)
print(ids.shape, distances.shape)  # (5, 10) (5, 10)
print(ids[0])

See the quick start for index updates and Python examples for all three indexes. Native clustering needs no external k-means package. See threading and save/load paths for runtime conventions.

Choose the right building block

Component	Use case
Quantizer	Integrate 1-bit or multi-bit encoding and distance estimation into your system.
IVF	Memory-efficient partitioned search, with optional raw-vector reranking.
HNSW	Graph search directly over compact quantized vectors.
SymphonyQG	Fast graph search with raw or packed 4-bit/8-bit vector storage.

IVF and HNSW support adding and removing vectors; HNSW also supports explicit capacity resizing. See their guides for update costs and file compatibility. The library supports L2 and inner product; normalize vectors for cosine search.

Why RaBitQ?

• Compact codes: Choose 1-bit or multi-bit quantization for your memory and accuracy needs.
• Accurate estimates: An asymptotically optimal error bound supports distance estimation.
• Native CPU acceleration: Runtime AVX2/AVX-512 dispatch on x86-64 and NEON on ARM64.

Developed by the VectorDB group at Nanyang Technological University. For GPU support, see cuvs_rabitq.

RaBitQ across the vector-search ecosystem

The projects below illustrate adoption of RaBitQ techniques across vector search; this is not a list of direct dependencies on RaBitQ-Library.

txtai uses the library as an ANN backend (configuration). Read how zvec integrates RaBitQ-Library for another integration example.

Milvus	Faiss	NVIDIA cuVS	Microsoft DiskANN	VSAG
VectorChord	Volcengine OpenSearch	CockroachDB	Elasticsearch	Apache Lucene
turbopuffer	Zvec	LanceDB	Databricks	ClickHouse
Qdrant	Weaviate

C++ quick start

Requires CMake 3.20+, a C++17 compiler with OpenMP, and an x86-64 CPU with AVX2/FMA or an ARM64 CPU. Build the library and examples:

git clone https://github.com/VectorDB-NTU/RaBitQ-Library.git
cd RaBitQ-Library
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel

Set -DRABITQ_ENABLE_NATIVE_OPTIMIZATION=OFF for binaries that will run on other CPUs. See platform-specific build instructions.

Use RaBitQ-Library in another C++ project

Add the repository as a submodule at third_party/rabitqlib, pin a release or commit, and link its CMake target:

set(RABITQ_BUILD_SAMPLES OFF CACHE BOOL "" FORCE)
add_subdirectory(third_party/rabitqlib)
target_link_libraries(my_program PRIVATE rabitqlib::rabitqlib)

The C++ API and ABI are evolving; update the pinned revision deliberately. For installed packages, use find_package(rabitqlib CONFIG REQUIRED) and the same target. Both approaches require OpenMP.

See submodule setup and version pinning, C++ installation, and the build and test guide for complete workflows. Examples: C++ indexes and quantization. Benchmarks: FAISS clustering comparison and GIST workflow.

Citation

If RaBitQ helps your research or system, please cite:

Jianyang Gao, Yutong Gou, Yuexuan Xu, Yongyi Yang, Cheng Long, and Raymond Chi-Wing Wong. “Practical and Asymptotically Optimal Quantization of High-Dimensional Vectors in Euclidean Space for Approximate Nearest Neighbor Search.” Proceedings of the ACM on Management of Data 3, 3, Article 202 (June 2025), 26 pages. https://doi.org/10.1145/3725413.

Yutong Gou, Jianyang Gao, Yuexuan Xu, and Cheng Long. “SymphonyQG: Towards Symphonious Integration of Quantization and Graph for Approximate Nearest Neighbor Search.” Proceedings of the ACM on Management of Data 3, 1, Article 80 (February 2025), 26 pages. https://doi.org/10.1145/3709730.

Jianyang Gao and Cheng Long. “RaBitQ: Quantizing High-Dimensional Vectors with a Theoretical Error Bound for Approximate Nearest Neighbor Search.” Proceedings of the ACM on Management of Data 2, 3, Article 167 (May 2024), 27 pages. https://doi.org/10.1145/3654970.

Contributing

Start with the contribution guide or starter tasks. Report bugs and request features through GitHub Issues. See maintenance and feedback for maintainer information.

Acknowledgements

RaBitQ Library is developed by Yutong Gou, Jianyang Gao, Yuexuan Xu, Jifan Shi, and Zhonghao Yang. We thank Alexandr Guzhva, Li Liu, Chao Gao, Silu Huang, Jiabao Jin, Xiaoyao Zhong, and Jinjing Zhou for their valuable feedback.

License

RaBitQ Library is available under the Apache License 2.0.