Contributors welcome! Help shape RaBitQ by reporting bugs, asking questions, suggesting features, or contributing code, tests, documentation, and examples. First-time contributors are welcome—open an issue or start with our contribution guide and starter tasks.

News

• September 2026 — Apple Silicon support: macOS ARM64 joins Linux and Windows x86-64, with NEON kernels and CPython 3.11–3.14 wheel builds for macOS 14+. See the platform requirements.

• September 2026 — Windows x86-64 support: C++ and Python source builds now support MSVC, runtime AVX2/AVX-512 dispatch, and Unicode index paths. Windows wheels are available for CPython 3.11–3.14. For source builds, see the Windows build instructions.

• September 2026 — IVF raw-vector reranking: Use nbits=32 for float32 reranking. Quantized IVF automatically selects HACC for 4–9-bit codes. See the IVF documentation.

• September 2026 — Quantized SymphonyQG: Set quantization_bits=4 or 8 for compact vector storage; raw vectors remain the default. See the SymphonyQG documentation.

Install

python -m pip install --upgrade rabitqlib

Wheels: CPython 3.11–3.14 on Linux and Windows x86-64, and macOS 14+ ARM64 (Apple Silicon). x86-64 uses AVX2/FMA with optional AVX-512 acceleration; ARM64 uses NEON and portable scalar kernels. macOS wheels bundle OpenMP; Intel Mac and universal2 wheels are not provided.

Python quick start

Build and search a small IVF index using synthetic data:

import numpy as np
from rabitqlib import IvfIndex

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

# Assign vectors to five clusters and calculate their centroids.
cluster_ids = (np.arange(len(data)) % 5).astype(np.uint32)
centroids = np.stack(
    [data[cluster_ids == cluster].mean(axis=0) for cluster in range(5)]
).astype(np.float32)

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

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

For all three indexes, build and search interpret num_threads=0 as the detected hardware thread count. Larger requests are capped at that count; smaller positive requests are respected. Operations may use fewer workers when there are fewer work items. If hardware detection is unavailable, one thread is used. Omitting num_threads in Python still defaults to one thread.

Python bindings are also available for HnswIndex and SymqgIndex. See the Python examples for index construction, querying, and index persistence. IVF and HNSW examples run Faiss clustering in a separate process, then pass saved clusters to RaBitQ indexing so their OpenMP runtimes stay separate.

Index save/load paths are UTF-8 strings on Windows and native path bytes on POSIX in C++; Python paths are Unicode strings on all platforms.

sudo apt-get update
sudo apt-get install -y build-essential cmake libomp-dev
git clone https://github.com/VectorDB-NTU/RaBitQ-Library.git
cd RaBitQ-Library
python -m pip install .

Choose the right building block

IVF and SymphonyQG use FastScan for batched estimates, while HNSW uses single-code kernels selected for the target architecture.

In typical workloads, 4-bit, 5-bit, and 7-bit quantization can achieve roughly 90%, 95%, and 99% recall, respectively, without reranking. Actual results depend on the dataset, index configuration, and search parameters.

Why RaBitQ?

The library supports Euclidean distance and inner product. Cosine search is available by normalizing vectors before using inner product.

RaBitQ is developed by the VectorDB group at Nanyang Technological University, Singapore. A GPU implementation is also available in 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.

Integration story: How zvec integrates RaBitQ-Library traces its use of the library's quantizers and estimators inside zvec's IVF and HNSW implementations, with links to the source code.

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

C++ quick start

Requirements

• CMake 3.20 or newer
• a C++17 compiler with OpenMP support
• an x86-64 CPU with AVX2 and FMA, or an Apple Silicon Mac

Clone and build the library and example programs:

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

For MSVC, follow the Windows build instructions. For Apple Silicon source builds, see the macOS ARM64 instructions. The ARM kernel sources use portable AArch64 intrinsics, but macOS tests do not establish Linux ARM64 support. Local GCC/Clang builds enable -march=native by default; set -DRABITQ_ENABLE_NATIVE_OPTIMIZATION=OFF for portable binaries, as release wheels do. See CPU dispatch details for backend requirements and fallbacks.

Use RaBitQ-Library in another C++ project

The C++ API and ABI are still evolving. For reproducible builds, pin a release or commit and include RaBitQ-Library as a Git submodule:

git submodule add https://github.com/VectorDB-NTU/RaBitQ-Library.git third_party/rabitqlib
git submodule update --init --recursive

Add the library and link its namespaced target in the consuming project's CMakeLists.txt:

set(RABITQ_BUILD_SAMPLES OFF CACHE BOOL "" FORCE)
add_subdirectory(third_party/rabitqlib)

target_link_libraries(my_program PRIVATE rabitqlib::rabitqlib)

Update the pinned revision deliberately when you are ready to adopt upstream changes:

git -C third_party/rabitqlib fetch
git -C third_party/rabitqlib checkout <release-or-commit>
git add third_party/rabitqlib

cmake -S . -B build \
  -DRABITQ_BUILD_SAMPLES=OFF \
  -DRABITQ_ENABLE_NATIVE_OPTIMIZATION=OFF \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_INSTALL_PREFIX="$HOME/.local"
cmake --build build --parallel
cmake --install build

find_package(rabitqlib CONFIG REQUIRED)
target_link_libraries(my_program PRIVATE rabitqlib::rabitqlib)

cmake -S . -B build -DCMAKE_PREFIX_PATH="$HOME/.local"
cmake --build build --parallel

Both integration methods require OpenMP on the consuming system.

The index example executables are written to bin/. Their source code shows the complete indexing and querying workflows:

• IVF + RaBitQ
• HNSW + RaBitQ
• SymphonyQG

A separate RaBitQ quantization example demonstrates the lower-level quantizer API; it is provided as source and is not currently a CMake target.

To build and run the C++ test suite:

cmake -S . -B build -DRABITQ_BUILD_TESTS=ON -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel
ctest --test-dir build --output-on-failure

GoogleTest is downloaded during test configuration. For a full benchmark on the GIST dataset, see example.sh. More detailed API and algorithm guidance is available in the documentation.

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

Contributions are welcome, including documentation and examples. Start with your first contribution or choose a small starter task. The guide explains which build, test, and formatting checks apply to your change.

See maintenance and feedback for the current maintainer. Use GitHub Issues for bugs, feature requests, and usage or contribution questions.

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.