kANNolo
kANNolo is a research-oriented library for Approximate Nearest Neighbors (ANN) search written in Rust 🦀. It is explicitly designed to combine usability with performance effectively. Designed with modularity and researchers in mind, kANNolo makes prototyping new ANN search algorithms and data structures easy. kANNolo supports both dense and sparse embeddings seamlessly. It implements the HNSW graph index and Product Quantization.
Python Installation
Quick start (prebuilt wheels)
For most users, this is the easiest option:
pip install kannolo
The prebuilt wheel includes dense and sparse HNSW indexes. If a compatible wheel exists for your platform, pip downloads and installs it directly. If not, pip compiles from source.
To use multivector reranking (SparseMultivecRerankIndex, SparseMultivecTwoLevelsPQRerankIndex), build from source with the multivec feature enabled (see Building from source below).
Building from source (maximum performance)
For maximum performance optimized to your CPU, build from source. Choose one of the two approaches below:
Shared Prerequisites
Both building approaches require Rust and nightly:
- Install Rust (via
rustup):
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
- Activate nightly:
rustup install nightly
rustup default nightly
Approach 1: Build from PyPI source
Compile and install directly from PyPI with CPU optimization (dense and sparse indexes only):
RUSTFLAGS="-C target-cpu=native" pip install --no-binary :all: kannolo
This installs the package in your system/virtual environment site-packages. For multivector reranking support, use Approach 2 instead.
Approach 2: Build from GitHub (development mode)
Clone the repository and build for development/modification:
- Clone and prepare:
git clone https://github.com/TusKANNy/kannolo.git
cd kannolo
- Create a virtual environment (recommended):
python3 -m venv ./venv
source ./venv/bin/activate # On Windows: venv\Scripts\activate
Alternatively, use conda:
conda create -n kannolo python=3.11
conda activate kannolo
- Install maturin:
pip install maturin
-
Build and install in editable mode:
Dense and sparse indexes only (default, lighter build):
RUSTFLAGS="-C target-cpu=native" maturin develop --release
With multivector reranking support (
SparseMultivecRerankIndex,SparseMultivecTwoLevelsPQRerankIndex):RUSTFLAGS="-C target-cpu=native" maturin develop --release --features multivec
Why use editable mode? Changes to Python code take effect immediately without reinstalling. Perfect for development and prototyping.
- Verify installation:
python -c "import kannolo; print('Successfully installed kannolo!')"
Rust
The crate exposes three feature flags:
| Feature | What it enables | Default |
|---|---|---|
multivec |
Multivector reranking indexes (SparseMultivecRerankIndex, SparseMultivecTwoLevelsPQRerankIndex) and the hnsw_rerank_search CLI binary |
No |
python |
PyO3 bindings — activated automatically by maturin when building the Python wheel | No |
cli |
CLI binaries: hnsw_build, hnsw_search, hnsw_rerank_{build,search}_{dense,sparse}, ivf_build, ivf_search (combine with multivec to also get hnsw_rerank_search) |
No |
If you want to compile the library only (dense and sparse indexes, no multivec, no binaries):
RUSTFLAGS="-C target-cpu=native" cargo build --release
If you want the CLI binaries hnsw_build, hnsw_search, the two-stage hnsw_rerank_{build,search}_{dense,sparse}, ivf_build and ivf_search (dense and sparse):
RUSTFLAGS="-C target-cpu=native" cargo build --release --features cli
If you want multivector reranking in the library (adds SparseMultivecRerankIndex and SparseMultivecTwoLevelsPQRerankIndex):
RUSTFLAGS="-C target-cpu=native" cargo build --release --features multivec
If you want all CLI binaries including hnsw_rerank_search:
RUSTFLAGS="-C target-cpu=native" cargo build --release --features "cli,multivec"
The resulting binaries are placed in target/release/.
Details on how to use kANNolo's core engine in Rust 🦀 can be found in docs/RustUsage.md.
Details on how to use kANNolo's Python interface can be found in docs/PythonUsage.md.
Resources
Check out our docs folder for a more detailed guide on how to use kANNolo directly in Rust, replicate the results of our paper, or use kANNolo with your custom collection.
📚 Bibliography
Leonardo Delfino, Domenico Erriquez, Silvio Martinico, Franco Maria Nardini, Cosimo Rulli and Rossano Venturini. "kANNolo: Sweet and Smooth Approximate k-Nearest Neighbors Search." Proc. ECIR. 2025.
Citation License
The source code in this repository is subject to the following citation license:
By downloading and using this software, you agree to cite the under-noted paper in any kind of material you produce where it was used to conduct a search or experimentation, whether be it a research paper, dissertation, article, poster, presentation, or documentation. By using this software, you have agreed to the citation license.
ECIR 2025
@InProceedings{10.1007/978-3-031-88717-8_29,
author = "Leonardo Delfino and
Domenico Erriquez and
Silvio Martinico and
Franco Maria Nardini and
Cosimo Rulli and
Rossano Venturini",
title = "kANNolo: Sweet and Smooth Approximate k-Nearest Neighbors Search",
booktitle = "Advances in Information Retrieval",
year = "2025",
publisher = "Springer Nature Switzerland",
pages = "400--406",
isbn = "978-3-031-88717-8"
}
1 maintainer
Metadata
1 maintainer
Release files for kannolo 0.12.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| kannolo-0.12.0.tar.gz | 747.4 kB | Details |
Built distributions (wheels)
Total release size: 17.5 MB
Release files / kannolo-0.12.0.tar.gz
| Download URL | kannolo-0.12.0.tar.gz |
|---|---|
| Size | 747.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9e44095ae27636b8f7e52dc59ac6ede1f2a7ac148cddaa2dd365259b1d51d7fd
|
|
BLAKE2b-256 checksum How to use checksums |
73621faa2be886bbfce6381ce4d8d840addf5e98342d078df5ebe3c6ac090ba8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / kannolo-0.12.0-cp313-cp313-manylinux_2_34_x86_64.whl
| Download URL | kannolo-0.12.0-cp313-cp313-manylinux_2_34_x86_64.whl |
|---|---|
| Size | 1.6 MB |
| Tags | CPython 3.13 Linux glibc 2.34+ x86-64 |
|
SHA-256 checksum How to use checksums |
a2210babae13433b967bbae7f73c1dde872a4fd9e4d3d6b61bf5aa2a37775151
|
|
BLAKE2b-256 checksum How to use checksums |
705ad4dafc2063f433397e6e522febe611273aa491f6b1d04b3b9d30d5110207
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / kannolo-0.12.0-cp313-cp313-macosx_11_0_arm64.whl
| Download URL | kannolo-0.12.0-cp313-cp313-macosx_11_0_arm64.whl |
|---|---|
| Size | 1.2 MB |
| Tags | CPython 3.13 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
d81adb1a4a30c59fcadd9860e17107f4972f4aa1bf2fecaffe3303bf655238a3
|
|
BLAKE2b-256 checksum How to use checksums |
ff33eccf6c7bf7f2bb7d7eebf0358650a10791da735fdaab80cf345663f7da0c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / kannolo-0.12.0-cp313-cp313-macosx_10_12_x86_64.whl
| Download URL | kannolo-0.12.0-cp313-cp313-macosx_10_12_x86_64.whl |
|---|---|
| Size | 1.4 MB |
| Tags | CPython 3.13 macOS 10.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
95c2ce8a63101ba061d7d8aa0748332ba90ac4b11e84c3f8359b7d5b9f3eed14
|
|
BLAKE2b-256 checksum How to use checksums |
5dd6f268fd253c84ba54b4a3c9552d8da8aea2ffa66fc4b5769e44890ff999bc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / kannolo-0.12.0-cp312-cp312-manylinux_2_34_x86_64.whl
| Download URL | kannolo-0.12.0-cp312-cp312-manylinux_2_34_x86_64.whl |
|---|---|
| Size | 1.6 MB |
| Tags | CPython 3.12 Linux glibc 2.34+ x86-64 |
|
SHA-256 checksum How to use checksums |
db4778bdc572ffe8c71cd5c1bd68a2b3527e030107ac03016cfb670754a4af1a
|
|
BLAKE2b-256 checksum How to use checksums |
b6240f3caa79bcad175f8772d4d6d1c4f389e824b411e4b5acfe549e2bed0056
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / kannolo-0.12.0-cp312-cp312-macosx_11_0_arm64.whl
| Download URL | kannolo-0.12.0-cp312-cp312-macosx_11_0_arm64.whl |
|---|---|
| Size | 1.2 MB |
| Tags | CPython 3.12 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
f6d937c1c6a394b0ac6bf9ff6ec5e5e9c33c00017d7bc064a5af40a06a58aa28
|
|
BLAKE2b-256 checksum How to use checksums |
2051a8bf35bd6f60cb6c7a41787b99bac86202cf422d36a7c599a1613976dbe2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / kannolo-0.12.0-cp312-cp312-macosx_10_12_x86_64.whl
| Download URL | kannolo-0.12.0-cp312-cp312-macosx_10_12_x86_64.whl |
|---|---|
| Size | 1.4 MB |
| Tags | CPython 3.12 macOS 10.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
8c04d788fa8a71f16e171b9e7e7b2a5e5328fa1dc5568c658a4edbc77cafd284
|
|
BLAKE2b-256 checksum How to use checksums |
8f5b37aa62d69a8fd2534e8a1df7030f6410c09ace6f141efe6f2018fb915a4a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / kannolo-0.12.0-cp311-cp311-manylinux_2_34_x86_64.whl
| Download URL | kannolo-0.12.0-cp311-cp311-manylinux_2_34_x86_64.whl |
|---|---|
| Size | 1.5 MB |
| Tags | CPython 3.11 Linux glibc 2.34+ x86-64 |
|
SHA-256 checksum How to use checksums |
13180529e08be4c2562612ed47442123a9e2c35b297fd40bda6c74e48009a71b
|
|
BLAKE2b-256 checksum How to use checksums |
fe5880ed8bd8b7e55b197e9006960f49e3ecc452670fa00d509d488bc3141500
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / kannolo-0.12.0-cp311-cp311-macosx_11_0_arm64.whl
| Download URL | kannolo-0.12.0-cp311-cp311-macosx_11_0_arm64.whl |
|---|---|
| Size | 1.2 MB |
| Tags | CPython 3.11 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
fe24c767d92e31ac8a70a62ac0ed092ec0690e89281530ed99985c601b6e0560
|
|
BLAKE2b-256 checksum How to use checksums |
d312b354af8995d59240f1d03a603c600b5e3e46fb93532cedfeab01430a16a5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / kannolo-0.12.0-cp311-cp311-macosx_10_12_x86_64.whl
| Download URL | kannolo-0.12.0-cp311-cp311-macosx_10_12_x86_64.whl |
|---|---|
| Size | 1.4 MB |
| Tags | CPython 3.11 macOS 10.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
ab4a0d1003d9dfe0bdfe4f0849756abd430f5332e51bd461e74baa10b13f1836
|
|
BLAKE2b-256 checksum How to use checksums |
1d4a8e2fe3f064314755f674579015a8bb4dbb291af96fe04ef2f3a535f65b7d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / kannolo-0.12.0-cp310-cp310-manylinux_2_34_x86_64.whl
| Download URL | kannolo-0.12.0-cp310-cp310-manylinux_2_34_x86_64.whl |
|---|---|
| Size | 1.5 MB |
| Tags | CPython 3.10 Linux glibc 2.34+ x86-64 |
|
SHA-256 checksum How to use checksums |
ea9eb2fbb7dbde0830912741d79d31494334c594babd0b703a1d653f7efd5c6f
|
|
BLAKE2b-256 checksum How to use checksums |
f122c17cc864b6372fb1349b97ccbddd0c09b90d90e9137f43608bcef0aeda41
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / kannolo-0.12.0-cp310-cp310-macosx_11_0_arm64.whl
| Download URL | kannolo-0.12.0-cp310-cp310-macosx_11_0_arm64.whl |
|---|---|
| Size | 1.2 MB |
| Tags | CPython 3.10 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
13b45b54332b8e825d8a28dcb9ba8f080cbe4b359d522d322cc556721fd5c2ed
|
|
BLAKE2b-256 checksum How to use checksums |
2d44f77cb64fc6745bdda46c2aa93b7b5c58e29934fa553342a8bf6b7867677c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / kannolo-0.12.0-cp310-cp310-macosx_10_12_x86_64.whl
| Download URL | kannolo-0.12.0-cp310-cp310-macosx_10_12_x86_64.whl |
|---|---|
| Size | 1.4 MB |
| Tags | CPython 3.10 macOS 10.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
cbe30dd574a6146198c229285470de43330eec00d3728e5808458c30ceefec72
|
|
BLAKE2b-256 checksum How to use checksums |
acf09052541f483edc2bfa7bdfa0813795beda451f57e568fba5b62d2489bea8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
