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.0.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.0-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.0-cp313-cp313-macosx_11_0_arm64.whl (900.2 kB view details)

Uploaded CPython 3.13macOS 11.0+ ARM64

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

Uploaded CPython 3.13macOS 10.12+ x86-64

kannolo-0.8.0-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.0-cp312-cp312-macosx_11_0_arm64.whl (900.3 kB view details)

Uploaded CPython 3.12macOS 11.0+ ARM64

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

Uploaded CPython 3.12macOS 10.12+ x86-64

kannolo-0.8.0-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.0-cp311-cp311-macosx_11_0_arm64.whl (904.4 kB view details)

Uploaded CPython 3.11macOS 11.0+ ARM64

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

Uploaded CPython 3.11macOS 10.12+ x86-64

kannolo-0.8.0-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.0-cp310-cp310-macosx_11_0_arm64.whl (904.7 kB view details)

Uploaded CPython 3.10macOS 11.0+ ARM64

kannolo-0.8.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.8.0.tar.gz.

File metadata

  • Download URL: kannolo-0.8.0.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.0.tar.gz
Algorithm Hash digest
SHA256 6522b97189eadea57d32a2a92094a38a97e9c5520903eb9f2a665444b6f0dccb
MD5 c02c34c246be2e1f176aab90d421ce96
BLAKE2b-256 60c07285ee2195f2585933cf57b10bd88abcc70aacf0b32d6b359609f3ab9813

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.8.0-cp313-cp313-manylinux_2_34_x86_64.whl
Algorithm Hash digest
SHA256 a58a90213a7015c1299a5372a6d9869fee48f7de58bc519ae3d9199e790aa081
MD5 c7f0991302648cb8e2d2b217852d567c
BLAKE2b-256 6f44431352681ba7044b09649c87652c71b41a82fc6e261644ac14d1fb7322d3

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.8.0-cp313-cp313-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 809ade9031967f430da52f7928ab53616bf408cbacb89c7aae62bd06f74563d6
MD5 3a291331e2bbdd0ed609eaa3151a3792
BLAKE2b-256 a792efb1cf73e5f7d284d1a5dd78faaa640e900aeaffda6b5922ed149d10a3b8

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.8.0-cp313-cp313-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 f146fd795cb56b06b384f8d878dd6de25559a4af2aa48bd53a5b5cfc3f4faeb3
MD5 c4636356010d1f8d728d644f5892609b
BLAKE2b-256 7acc7c9001450d6f66813423f2992b886fb340b42eefc3545ac3c151dacaeb29

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.8.0-cp312-cp312-manylinux_2_34_x86_64.whl
Algorithm Hash digest
SHA256 bc9c0942e3902bece67ad0544a0af84e3ecf40bd8c9545eac81a867ed31f197d
MD5 99265bed2d82b7adf70678fa69e2211e
BLAKE2b-256 418d558fe2f67b5b2bd8c91018284a26180ad4d5740251915934756ae37d687d

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.8.0-cp312-cp312-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 08b2211248d5db7e6c3f097df4c0e5d05057a15a38ea064a27c3bff207014c73
MD5 f4b5050819baca88654388a95a2a29cd
BLAKE2b-256 4c8a1f8867aa33bf6c00ffc8fe1828d8c072f92d7ac4713db056ad0acab473e4

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.8.0-cp312-cp312-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 deae82f437d8bacaace260d3c5239f7cbff5199bc40169de83826af13cec3020
MD5 7178b458c213226499b584d42a6e590c
BLAKE2b-256 add6ade1080276ab9d4a604928d416e052cf411c52ac499bec00ff18c3f41dbd

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.8.0-cp311-cp311-manylinux_2_34_x86_64.whl
Algorithm Hash digest
SHA256 19924e51e869d281770bbe5c11376ea3450a59fa4e85b39f98b801ddfbb8adbf
MD5 07650af197148c5b8390b9730d6ef065
BLAKE2b-256 d32f41f10a859e49452f340fdd3d6cbd8a28184b18c8e1dde9a2e36b13df3a26

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.8.0-cp311-cp311-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 7ab4870456508ef65df2817933fc77b6eedfeed8cd3fdb0888f7aa7b1b6f7bf1
MD5 efb64144d5f8979a0658da0fcb0be095
BLAKE2b-256 8ddf61d68bdc5b28240b96b67fb623813eaf6717e3ee445268b932c6ea02a1e9

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.8.0-cp311-cp311-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 e3c0b9a54a622e87f44dcbe4e925925cd627ef32edbc215b8da370b93b5b2df5
MD5 564fe4f4ae6ede4b849526c8b0482569
BLAKE2b-256 40c980e896a70443646963b7e0b6540c4b89a2e784fadde575454b4de3c1e815

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.8.0-cp310-cp310-manylinux_2_34_x86_64.whl
Algorithm Hash digest
SHA256 8ccd0eb01d47e6ed74e86e95244b8b7b1736e9b5eb1f16ba11c631ed1bb03dd0
MD5 3572bbeaf9b69aceb9dd9e29c480c8c2
BLAKE2b-256 688592e1314a8bf3e3bfd5e31578bd15cf2d3a6e5668a6945602c892aa9cbba1

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.8.0-cp310-cp310-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 3d89962406007e06c038c68fc71af412da52f2a202a3aba84468dd252d794b52
MD5 fdbdb9ee22abaf090d733de51851cfa3
BLAKE2b-256 d049a59de7fa4f77c7cd0867cfe63cbf7619c9ac3fdaa6b5d7fd24d87afbff72

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.8.0-cp310-cp310-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 de8413b510b6250b2012c309a4ce20134208c5fa038d1fb5f8bb1dda056f444c
MD5 427f6a9ccb37ab52f409195c9126526b
BLAKE2b-256 aa2445bb22fa6b4ce9b3acf3dbc6256609e8f28b9c4bc9eb0423b5938b22913c

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

0.8.1

13 files

This release

0.8.0 This release

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