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.9.0.tar.gz (709.2 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.9.0-cp313-cp313-manylinux_2_34_x86_64.whl (1.2 MB view details)

Uploaded CPython 3.13manylinux: glibc 2.34+ x86-64

kannolo-0.9.0-cp313-cp313-macosx_11_0_arm64.whl (900.5 kB view details)

Uploaded CPython 3.13macOS 11.0+ ARM64

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

Uploaded CPython 3.13macOS 10.12+ x86-64

kannolo-0.9.0-cp312-cp312-manylinux_2_34_x86_64.whl (1.2 MB view details)

Uploaded CPython 3.12manylinux: glibc 2.34+ x86-64

kannolo-0.9.0-cp312-cp312-macosx_11_0_arm64.whl (900.7 kB view details)

Uploaded CPython 3.12macOS 11.0+ ARM64

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

Uploaded CPython 3.12macOS 10.12+ x86-64

kannolo-0.9.0-cp311-cp311-manylinux_2_34_x86_64.whl (1.2 MB view details)

Uploaded CPython 3.11manylinux: glibc 2.34+ x86-64

kannolo-0.9.0-cp311-cp311-macosx_11_0_arm64.whl (907.5 kB view details)

Uploaded CPython 3.11macOS 11.0+ ARM64

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

Uploaded CPython 3.11macOS 10.12+ x86-64

kannolo-0.9.0-cp310-cp310-manylinux_2_34_x86_64.whl (1.2 MB view details)

Uploaded CPython 3.10manylinux: glibc 2.34+ x86-64

kannolo-0.9.0-cp310-cp310-macosx_11_0_arm64.whl (907.6 kB view details)

Uploaded CPython 3.10macOS 11.0+ ARM64

kannolo-0.9.0-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.9.0.tar.gz.

File metadata

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

File hashes

Hashes for kannolo-0.9.0.tar.gz
Algorithm Hash digest
SHA256 9398ffaff7dc878305d4cfd07501c273f42b6a0fa9e1ca8d5010183ebb747ef1
MD5 45804faabf2022523fbc3353c66116ec
BLAKE2b-256 51536357c3e0f2ce17f9c6b8e619440638cce4c2afcf3a71435f17da492c51d4

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.9.0-cp313-cp313-manylinux_2_34_x86_64.whl
Algorithm Hash digest
SHA256 7d69c4962dd582fe49e1ea28ac1c7604a288dec67776f517f67587544c3a5701
MD5 6a51aafb15f78ccce9e8462fe5e33022
BLAKE2b-256 9bc6edc7f69aeece478b77a7ed3aff59a05b5499461a061b8116d576b7994d0e

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.9.0-cp313-cp313-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 6490d22b97c5793dadfd2b07b692d9bf7e5cfe3531f3cfc958efa776df841197
MD5 a5a13104d58f18957661ba6f0665efe9
BLAKE2b-256 35093ebe7be0484e382a5f7f56b2dc2b77552abb380f09c9a7e1de0da470c0f0

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.9.0-cp313-cp313-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 70805a7a916f2c1d26a84a1ddd8f44e8af4e38b16b3a8da68bcdd3dc35b2d4ce
MD5 ca7aab2b45fb551f34fde4b6d6df4014
BLAKE2b-256 88833c98301653a21d9d6829e66351aac8cc1177cc01954b25c0e72fa732bbb9

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.9.0-cp312-cp312-manylinux_2_34_x86_64.whl
Algorithm Hash digest
SHA256 6242be4e9cbd734a732397423ef3e7420c3091574465bb7eb9ba90329a63f7db
MD5 404c0538c6e3f3d3c2de24dd962fc901
BLAKE2b-256 c50432f0202b3cc619aef73652dc486470bba4e312a8af4579bddc7251edec45

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.9.0-cp312-cp312-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 ddf65fd2e463990456ecf6395a638b0857b36392f5b35c098ca5955f22f93bed
MD5 8695c87418341735a2870d9050c05b84
BLAKE2b-256 ad8c52a3dbd6d81cdb7dcba56bc9c18e97fe85f1b82e71ea739d58d69519e3b9

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.9.0-cp312-cp312-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 eab1f1675a2371abe02e049b3b932fedb0c760966cf3f23dc270dd3f4d9aa85e
MD5 3527a126a0463d69cb1ce17a761127b3
BLAKE2b-256 cdd5583a008e4143ed65e46d5a5df87e88e336d31956243e5235bf93351239b3

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.9.0-cp311-cp311-manylinux_2_34_x86_64.whl
Algorithm Hash digest
SHA256 61843b69577d5b71b52ba6c56f90df5f950215312662504b9bff236de6fd9ea9
MD5 7203acecb953be72a15282865895e71b
BLAKE2b-256 7ac85359dc0ebe02dbe811c0168f84d29085eefc0d62fc153555903f055d9eb1

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.9.0-cp311-cp311-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 6b3666c12a7599482cd7e594e574e02f6b502a23d8de6e4972a8a517245bcd7f
MD5 48a00db2445044749851368becde5133
BLAKE2b-256 fcc1b345f83f84869562f9f8c4d0631aed1f94aa01aebb23b2754022d79874f2

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.9.0-cp311-cp311-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 996dacfc5f2b97117dd068215570b2a0bdd48c8ee4f1f0ac7ea28f53f1af9b48
MD5 d53bb483adbaed1e836e3fc4f9f9967e
BLAKE2b-256 9d6d2b8b815298619fd4a86a01ca72d71a2782cfb5925ca1228c3cd7bac480ad

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.9.0-cp310-cp310-manylinux_2_34_x86_64.whl
Algorithm Hash digest
SHA256 8a318986146eece168edd8fa3920b5673d2f404300706524b9a5724316d54fc1
MD5 a3e9f314809e83686b7d06d9a54f8324
BLAKE2b-256 e56532964e72ce62690db38702d03d3542ae5051ebaa8b0c82211d6cd2cb6b12

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.9.0-cp310-cp310-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 c1d8d72a186805e505d4508c80bbdcfadce82843c6d08a1fbe05a8afeeec9092
MD5 b481cd18bba24c53dcc020f53270bedb
BLAKE2b-256 0067cd96cc5435a73df8c6c7121520a9db586bc77810e8b6ab1c0043de34ba99

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.9.0-cp310-cp310-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 e786c36bce61a3d4ee86d98adbe48ae97cf094946ad66b8aeac644ff930a4980
MD5 9b326b5b63706611e87b8b83d69a59c7
BLAKE2b-256 e89ba4ae4f53811295c503f458e591a8d8f6a84cb72a233d44933f8189287e51

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

This release

0.9.0 This release

13 files

0.8.1

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