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, and SymphonyQG.

PyPI Python versions C++ tests Python tests Documentation Paper DOI License

Documentation · Python package · Paper · Releases

Install

pip install rabitqlib

Prebuilt wheels support Linux x86-64 and CPython 3.9–3.14. AVX2 + FMA is the portable CPU baseline; supported AVX-512 kernels are selected at runtime.

Adopted across the vector-search ecosystem

Milvus · Faiss · VSAG · VectorChord · Volcengine OpenSearch · CockroachDB · Elasticsearch · Lucene · turbopuffer · Zvec

Accuracy at a glance

RaBitQ estimation error benchmark across MSong, YouTube, OpenAI embeddings, Word2Vec, and GIST

Average and maximum relative estimation error across six datasets; lower is better. Results from the SIGMOD camera-ready paper.

Why RaBitQ?
Compact by design Choose 1-bit or multi-bit codes to match your memory and accuracy target.
Accurate estimates An asymptotically optimal theoretical error bound supports reliable ordering and reranking.
Fast on x86-64 Dedicated AVX2 and AVX-512 kernels are selected through runtime CPU dispatch.
Ready for ANN search Use the quantizer directly or build complete IVF, HNSW, and SymphonyQG indexes.

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.

Python quick start

The following complete example builds a small IVF index and searches it. It uses deterministic synthetic data, so no dataset download is required.

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])

Python bindings are also available for HnswIndex and SymqgIndex. See the Python examples for index construction, querying, and index persistence.

Build the Python bindings from source

Source builds require a C++17 compiler, CMake 3.15 or newer, and OpenMP. On Ubuntu or Debian:

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 .

C++ quick start

Requirements

  • CMake 3.15 or newer
  • a C++17 compiler with OpenMP support
  • an x86-64 CPU supported by the selected kernels: most paths accept either AVX2 with FMA or AVX-512F/BW/DQ with FMA
CPU dispatch details

Most SIMD entry points select AVX-512 kernels when AVX-512F, AVX-512BW, and AVX-512DQ are detected; otherwise they use AVX2 when AVX2 and FMA are available. AVX-512 VPOPCNTDQ enables additional popcount kernels. The HNSW AVX-512 core path also checks for AVX2 and FMA. AVX-512 translation units are compiled with FMA enabled.

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

Release builds enable native CPU tuning by default. To build a binary that can be moved between AVX2- and AVX-512-capable machines, configure with -DRABITQ_ENABLE_NATIVE_OPTIMIZATION=OFF; the ISA-specific kernels will still be selected at runtime.

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

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.

Choose the right building block

Component Best fit Storage and search profile
Quantizer Integrating RaBitQ into an existing system Low-level 1-bit or multi-bit encoding and distance estimation.
IVF Memory-efficient partitioned search Stores quantized codes without retaining the raw dataset.
HNSW Graph search with compact vectors Adds graph links and searches directly from quantized codes.
SymphonyQG Query speed when more memory is available Retains raw vectors and stores per-neighborhood quantization data.

IVF and SymphonyQG use FastScan for batched estimates, while HNSW uses single-code AVX2 or AVX-512 kernels.

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.

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.

Contributing

Contributions are welcome. See the contributing guide for the build, formatting, pre-commit, and static-analysis workflows.

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.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.3.2)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for TamimEhsan from gravatar.com TamimEhsan

Requires

Python >=3.9

Provides Extra

test

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

rabitqlib-0.2.0-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (590.3 kB view details)

Uploaded CPython 3.14manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

rabitqlib-0.2.0-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (590.0 kB view details)

Uploaded CPython 3.13manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

rabitqlib-0.2.0-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (590.0 kB view details)

Uploaded CPython 3.12manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

rabitqlib-0.2.0-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (589.7 kB view details)

Uploaded CPython 3.11manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

rabitqlib-0.2.0-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (588.7 kB view details)

Uploaded CPython 3.10manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

rabitqlib-0.2.0-cp39-cp39-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (588.9 kB view details)

Uploaded CPython 3.9manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

File details

Details for the file rabitqlib-0.2.0-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for rabitqlib-0.2.0-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 b6f508751f95c1e4f7215962eeba6d2cc69c5bc614c8e9240f93378da510d2ef
MD5 158218a5e23fafedb024a7f0da78723d
BLAKE2b-256 a30e550cd4954c971fbedb0d7b1d2918962f6ce136108353848289140e74fe90

See more details on using hashes here.

Provenance

The following attestation bundles were made for rabitqlib-0.2.0-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl:

Publisher: release.yml on VectorDB-NTU/RaBitQ-Library

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file rabitqlib-0.2.0-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for rabitqlib-0.2.0-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 f723a25a785a61eb2c12d3a028e7bbdcb9483425a394f2bb6e13f6020c504053
MD5 84cd291b88525bfa78639998a3bcc181
BLAKE2b-256 5e364456f2ce39ca3d961b4a0159b1647282aab30af2e070c92368b880f81257

See more details on using hashes here.

Provenance

The following attestation bundles were made for rabitqlib-0.2.0-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl:

Publisher: release.yml on VectorDB-NTU/RaBitQ-Library

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file rabitqlib-0.2.0-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for rabitqlib-0.2.0-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 6d838775460ea933775814b88bdfb7e5f368ae1c5a9b6056ddc509dcb29c3a3e
MD5 b7cc3ff4548047b230aff4ed7382a5ff
BLAKE2b-256 1af6b449149ed04fbc07e30a837e0679d67eb46939d5cf005dae5c8568ea2a7e

See more details on using hashes here.

Provenance

The following attestation bundles were made for rabitqlib-0.2.0-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl:

Publisher: release.yml on VectorDB-NTU/RaBitQ-Library

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file rabitqlib-0.2.0-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for rabitqlib-0.2.0-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 cf8cdf7a2b77088699b6e5760fc0a4cbb307b0b64081cba7b51531c65a5a961d
MD5 972d8326acc61443d5bb48ad11da6784
BLAKE2b-256 db29c3f7cc76048dc130270accf2469a41b7a5a57ec667f8fc525c83cad95d87

See more details on using hashes here.

Provenance

The following attestation bundles were made for rabitqlib-0.2.0-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl:

Publisher: release.yml on VectorDB-NTU/RaBitQ-Library

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file rabitqlib-0.2.0-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for rabitqlib-0.2.0-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 eca377560b799cbc4857eb3bf80e2cfa8c5bf0e011e8b360564e635076da1133
MD5 79cb21190c191181807fb10a2dff272c
BLAKE2b-256 12d40069e5b8f557f936e9439299190ef8058299af2765cb0e8a40d6cac58b98

See more details on using hashes here.

Provenance

The following attestation bundles were made for rabitqlib-0.2.0-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl:

Publisher: release.yml on VectorDB-NTU/RaBitQ-Library

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file rabitqlib-0.2.0-cp39-cp39-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for rabitqlib-0.2.0-cp39-cp39-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 e9dbc50edbbb1f046edfee5358505b9752dbd8811b4c5eb7e51f9d82822b8e60
MD5 3acfa6475447f094942653ab7098f04c
BLAKE2b-256 3bce2273773007434fa6dee628e3e8859ded7ddae3a3ecfb058f67aa57c18bc2

See more details on using hashes here.

Provenance

The following attestation bundles were made for rabitqlib-0.2.0-cp39-cp39-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl:

Publisher: release.yml on VectorDB-NTU/RaBitQ-Library

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.3.2

4 files

0.3.1

4 files

0.3.0

4 files

0.2.2

4 files

0.2.1

4 files

This release

0.2.0 This release

6 files

0.1.0

1 file

0.0.1

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page