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 Documentation Paper DOI License

Documentation · Python package · Paper · Releases

News

  • September 2026 — Quantized SymphonyQG: SymphonyQG now supports optional 4-bit and 8-bit RaBitQ vector storage. Select QG-quant with quantization_bits=4 or quantization_bits=8; vanilla raw-vector QG remains the default. See the SymphonyQG documentation for details.

Install

pip install rabitqlib

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

RaBitQ across the vector-search ecosystem

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

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 Fast graph search with a configurable memory/accuracy tradeoff Uses raw vectors by default, or optional packed 4-bit/8-bit RaBitQ vectors, alongside 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.

Project links

Data verified by PyPI on Sep 4, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

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

GitHub Statistics

Data verified by PyPI on Sep 4, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

Requires

Python >=3.11

Provides Extra

test

Classifiers

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.3.0-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (596.3 kB view details)

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

rabitqlib-0.3.0-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (596.1 kB view details)

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

rabitqlib-0.3.0-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (596.0 kB view details)

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

rabitqlib-0.3.0-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (595.7 kB view details)

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

File details

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

File metadata

File hashes

Hashes for rabitqlib-0.3.0-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 d771a3ad8cce57d40b67d3be7f8be6bb220bbd888dd2deef7c2664c2d6471362
MD5 5039bb4d7a3cb18525075549bb63fc83
BLAKE2b-256 5f7b82a9033ee3792ddc8f10a06c89e4100eca2f13104856c254465624f64096

See more details on using hashes here.

Provenance

The following attestation bundles were made for rabitqlib-0.3.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.3.0-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for rabitqlib-0.3.0-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 6ba4c46bedafd1780feb82e5dcc92d3202434b0da683932709519132d42c6194
MD5 1ae26382e95bf9b2d7e11da592f76d46
BLAKE2b-256 b9cbca13082f86cd981f8c4cff2b2afc8121b530a55734d4b30cc504570fa543

See more details on using hashes here.

Provenance

The following attestation bundles were made for rabitqlib-0.3.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.3.0-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for rabitqlib-0.3.0-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 82daadc67906859eeb32da91e285897a765d050b4f806951716dd6cc5d1fca71
MD5 48021694ec0f0e3e8e41f99a1d603c72
BLAKE2b-256 64be9a26884d990ab223299c5b1cffc9ec90ac0fd0ae72b9c0e190b87d722d97

See more details on using hashes here.

Provenance

The following attestation bundles were made for rabitqlib-0.3.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.3.0-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for rabitqlib-0.3.0-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 af02c59f9c8c46fb8dfd25a111afbc574f0d8ae8626bc1ee924381751ba4f450
MD5 129691fa9c437082c6271f122855381d
BLAKE2b-256 43792a227bec2ef475f818742c95e43883eb69af72cabefe6ad0feb209b9805b

See more details on using hashes here.

Provenance

The following attestation bundles were made for rabitqlib-0.3.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.

Release history Release notifications | RSS feed

0.3.2

4 files

0.3.1

4 files

This release

0.3.0 This release

4 files

0.2.2

4 files

0.2.1

4 files

0.2.0

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