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:

  1. Install Rust (via rustup):
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
  1. 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:

  1. Clone and prepare:
git clone https://github.com/TusKANNy/kannolo.git
cd kannolo
  1. 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
  1. Install maturin:
pip install maturin

  1. 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.

  1. 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 (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 and hnsw_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"
}

Key dates

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

1 maintainer

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

Credits

Author: Silvio Martinico

License

MIT License (MIT)

Requires

Python >=3.9

Tags

Approximate Nearest Neighbors Similarity Search indexing Rust

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 Distribution

kannolo-0.8.1.tar.gz (703.5 kB view details)

Uploaded Source

Built Distributions

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

kannolo-0.8.1-cp313-cp313-manylinux_2_34_x86_64.whl (1.1 MB view details)

Uploaded CPython 3.13manylinux: glibc 2.34+ x86-64

kannolo-0.8.1-cp313-cp313-macosx_11_0_arm64.whl (899.7 kB view details)

Uploaded CPython 3.13macOS 11.0+ ARM64

kannolo-0.8.1-cp313-cp313-macosx_10_12_x86_64.whl (1.1 MB view details)

Uploaded CPython 3.13macOS 10.12+ x86-64

kannolo-0.8.1-cp312-cp312-manylinux_2_34_x86_64.whl (1.1 MB view details)

Uploaded CPython 3.12manylinux: glibc 2.34+ x86-64

kannolo-0.8.1-cp312-cp312-macosx_11_0_arm64.whl (899.8 kB view details)

Uploaded CPython 3.12macOS 11.0+ ARM64

kannolo-0.8.1-cp312-cp312-macosx_10_12_x86_64.whl (1.1 MB view details)

Uploaded CPython 3.12macOS 10.12+ x86-64

kannolo-0.8.1-cp311-cp311-manylinux_2_34_x86_64.whl (1.1 MB view details)

Uploaded CPython 3.11manylinux: glibc 2.34+ x86-64

kannolo-0.8.1-cp311-cp311-macosx_11_0_arm64.whl (904.0 kB view details)

Uploaded CPython 3.11macOS 11.0+ ARM64

kannolo-0.8.1-cp311-cp311-macosx_10_12_x86_64.whl (1.1 MB view details)

Uploaded CPython 3.11macOS 10.12+ x86-64

kannolo-0.8.1-cp310-cp310-manylinux_2_34_x86_64.whl (1.1 MB view details)

Uploaded CPython 3.10manylinux: glibc 2.34+ x86-64

kannolo-0.8.1-cp310-cp310-macosx_11_0_arm64.whl (904.0 kB view details)

Uploaded CPython 3.10macOS 11.0+ ARM64

kannolo-0.8.1-cp310-cp310-macosx_10_12_x86_64.whl (1.1 MB view details)

Uploaded CPython 3.10macOS 10.12+ x86-64

File details

Details for the file kannolo-0.8.1.tar.gz.

File metadata

  • Download URL: kannolo-0.8.1.tar.gz
  • Upload date:
  • Size: 703.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for kannolo-0.8.1.tar.gz
Algorithm Hash digest
SHA256 dc6fb1009120fa00c748ffde1a6cf75a5af418ae123af4faa143c096ce392881
MD5 4e271de1ce6ed73d7bc3a3e7e715bf32
BLAKE2b-256 bdd2be6d3dd64d39096dc537362dc5065a6c9e77967f23af285059878f47d53d

See more details on using hashes here.

File details

Details for the file kannolo-0.8.1-cp313-cp313-manylinux_2_34_x86_64.whl.

File metadata

File hashes

Hashes for kannolo-0.8.1-cp313-cp313-manylinux_2_34_x86_64.whl
Algorithm Hash digest
SHA256 e388b858c0ca27687f45d8864ddb83c2c99f0d3475c5eb2163d63e0c5d455d48
MD5 c81199f613617a79ccbb628e86608928
BLAKE2b-256 f133e4d22f24c9ce3425fa05816e06e2faecaf82f0691c42520968baafa3acb5

See more details on using hashes here.

File details

Details for the file kannolo-0.8.1-cp313-cp313-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for kannolo-0.8.1-cp313-cp313-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 1d067f4ece4e4baba4d8d9bd8347425ed10f86e407759ea4bfcdde707e024436
MD5 3e6466e2f26b8b07cbd72f1244dedfc0
BLAKE2b-256 20daec591a2f66c395ea18fd8c605150dfae81e1076523565dd49c25e28aba89

See more details on using hashes here.

File details

Details for the file kannolo-0.8.1-cp313-cp313-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for kannolo-0.8.1-cp313-cp313-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 c044717b021e66d2e2985568edeeb8f25af5df0e2f54c2fb88da270898a6e918
MD5 443f711d25624f828d0f33bf05a066af
BLAKE2b-256 fe40004542ead536c643e2f65f7c750c9abf6cd771a932e78176b2b5dbfcc605

See more details on using hashes here.

File details

Details for the file kannolo-0.8.1-cp312-cp312-manylinux_2_34_x86_64.whl.

File metadata

File hashes

Hashes for kannolo-0.8.1-cp312-cp312-manylinux_2_34_x86_64.whl
Algorithm Hash digest
SHA256 f9402e8f2114d1aeba87da8f51ee4acfe45bee40c8581809393bbadf6187c338
MD5 c8f42d64cf2ee7dfe279caa84b685f7e
BLAKE2b-256 8c8813e6caddc79749d20ac04e512f7cce659569025169eda52ede38adad9b1d

See more details on using hashes here.

File details

Details for the file kannolo-0.8.1-cp312-cp312-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for kannolo-0.8.1-cp312-cp312-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 427a47f2908e72d5061bd6b6eff5f097b1fb9f69494127241ee6c701229c6c8f
MD5 0882091a075b2f3a7ecbd667b6d634bf
BLAKE2b-256 678f226652af0d2e65ab0453be5876cce81e216b8b4455a17530f7d9b2ac04f8

See more details on using hashes here.

File details

Details for the file kannolo-0.8.1-cp312-cp312-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for kannolo-0.8.1-cp312-cp312-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 5f18673f388064a7fdabc7573b58f30ec4f95d487a112f9506e98896679b8c70
MD5 c6f542f997bdb0226ef1561d5ab81df0
BLAKE2b-256 e4baef280aef7c6ed8a2b08f8abc0ec414ae20eec69ad6ba82bdb98ef34b516e

See more details on using hashes here.

File details

Details for the file kannolo-0.8.1-cp311-cp311-manylinux_2_34_x86_64.whl.

File metadata

File hashes

Hashes for kannolo-0.8.1-cp311-cp311-manylinux_2_34_x86_64.whl
Algorithm Hash digest
SHA256 8bd69aaa5ede45ce943d27e6975a939c5813ccafd070e96589e5c977740eec43
MD5 58981606a7100261fd30e1f116eaa6d1
BLAKE2b-256 d271f620e5ae9e836fd3351cbcffce3023b5440b539564f61e28ffa28be1e3d4

See more details on using hashes here.

File details

Details for the file kannolo-0.8.1-cp311-cp311-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for kannolo-0.8.1-cp311-cp311-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 b28e058d5089f1da6d8ff1737c67cc2099a307b425d3676331509af65842eef9
MD5 90dd941b8da60ba1f14c9dc388da3d78
BLAKE2b-256 f88e13193aae2aff4c1fa4e06964a951cbee84301fbccb3adda353b51016f76c

See more details on using hashes here.

File details

Details for the file kannolo-0.8.1-cp311-cp311-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for kannolo-0.8.1-cp311-cp311-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 932ba7b9cd569d572ac95279efba346496b150917728c03d77e49ac27d67a5f0
MD5 f13358aa4c0b2a8869c1b1778f60ded3
BLAKE2b-256 26cba9d78bf174b345b354a4d751e2e49f7031df6b320e20bc10f6d20b073358

See more details on using hashes here.

File details

Details for the file kannolo-0.8.1-cp310-cp310-manylinux_2_34_x86_64.whl.

File metadata

File hashes

Hashes for kannolo-0.8.1-cp310-cp310-manylinux_2_34_x86_64.whl
Algorithm Hash digest
SHA256 88dc343e9a4233d43a187c90a1ef909d866a931f8ac2a9ff8290674e684d21cc
MD5 9e01f9e394600281ad1979decc0bb36f
BLAKE2b-256 db48dc25ec0a4a90be6ed099f6d778e88c9375a4492e6e80454a80379774f222

See more details on using hashes here.

File details

Details for the file kannolo-0.8.1-cp310-cp310-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for kannolo-0.8.1-cp310-cp310-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 687b4579a343dc07d1fc59400bc98b5cd43507b51d25e5ccf478e275279f4c83
MD5 1c13ab2baa67bc10a148cd9f7b2e1711
BLAKE2b-256 7ec0b9667f039fb47e66c74595ddc1d81bd6048a6c8c955877f7595e86768bc0

See more details on using hashes here.

File details

Details for the file kannolo-0.8.1-cp310-cp310-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for kannolo-0.8.1-cp310-cp310-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 57e3247520c512d99883a9b9f119cc68454b4bf072bcac7fb6ec703548fdec20
MD5 465f12734c885fbff76c113f85f854ed
BLAKE2b-256 605f54023fde845c4c393cd1acaae2edafdadd2e5d7a67e2478f2273beca6042

See more details on using hashes here.

Release history Release notifications | RSS feed

0.10.0

13 files

0.9.2

13 files

0.9.1

13 files

0.9.0

13 files

This release

0.8.1 This release

13 files

0.8.0

13 files

0.7.1

13 files

0.7.0

13 files

0.6.1

13 files

0.6.0

13 files

0.5.5

13 files

0.5.4

13 files

0.5.3

13 files

0.5.2

13 files

0.5.1

13 files

0.5.0

13 files

0.4.9

13 files

0.4.8

13 files

0.4.7

13 files

0.4.6

21 files

0.4.5

21 files

0.4.4

2 files

0.4.3

2 files

0.4.2

2 files

0.4.1

2 files

0.4.0

2 files

0.3.8

2 files

0.3.7

2 files

0.3.6

2 files

0.3.5

2 files

0.3.4

2 files

0.3.3

2 files

0.3.2

2 files

0.3.1

2 files

0.3.0

2 files

0.2.5

2 files

0.2.4

2 files

0.2.3

2 files

0.2.2

2 files

0.2.1

2 files

0.2.0

2 files

0.1.7

2 files

0.1.6

2 files

0.1.5

2 files

0.1.3

2 files

0.1.2

2 files

0.1.1

2 files

0.1.0

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page