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:
Latest release

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.10.0.tar.gz (716.7 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.10.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.10.0-cp313-cp313-macosx_11_0_arm64.whl (895.9 kB view details)

Uploaded CPython 3.13macOS 11.0+ ARM64

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

Uploaded CPython 3.13macOS 10.12+ x86-64

kannolo-0.10.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.10.0-cp312-cp312-macosx_11_0_arm64.whl (896.0 kB view details)

Uploaded CPython 3.12macOS 11.0+ ARM64

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

Uploaded CPython 3.12macOS 10.12+ x86-64

kannolo-0.10.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.10.0-cp311-cp311-macosx_11_0_arm64.whl (902.7 kB view details)

Uploaded CPython 3.11macOS 11.0+ ARM64

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

Uploaded CPython 3.11macOS 10.12+ x86-64

kannolo-0.10.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.10.0-cp310-cp310-macosx_11_0_arm64.whl (902.7 kB view details)

Uploaded CPython 3.10macOS 11.0+ ARM64

kannolo-0.10.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.10.0.tar.gz.

File metadata

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

File hashes

Hashes for kannolo-0.10.0.tar.gz
Algorithm Hash digest
SHA256 4cf36fc82c501650893651214f79aa8aece79460f3f0feac940569a71a882eec
MD5 8be7019c964c87bf460eddff25f7e0a0
BLAKE2b-256 accba0d140d71effbe100b57ad216397ce2b240ce38328e85ad8f7c7424eb2cc

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.10.0-cp313-cp313-manylinux_2_34_x86_64.whl
Algorithm Hash digest
SHA256 87c04304606c77e9ad1303658c45d0b42c7d9611c6fb2896407463d8619bfdbe
MD5 abc5eff81b17bb24c263bc0ea1cba1d8
BLAKE2b-256 95ebcd6ebdf3cfc8793f759a55ab43438d75a64fd997036cc2d51769085622fa

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.10.0-cp313-cp313-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 ed9a475215ff32c0bbb7d13ae529e1b04b62e700aae8adde6fa46c5157cdd4ab
MD5 49b6fb701c0f8b6fa53a77858ad9d131
BLAKE2b-256 bebe1fb445180311d8ba04e14933fd1702d8dca488d952d13ebbfb194e138b62

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.10.0-cp313-cp313-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 b39169d163762937aa162a82ba082570a28d3c3c5e5b851653c2dd9ad82b9dea
MD5 49ce400ed3bb3300f2bc6162a84e5264
BLAKE2b-256 badbdb1504d08f81b203e305dba9d6928213945c97321ae2fef44aa50fb2ba8b

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.10.0-cp312-cp312-manylinux_2_34_x86_64.whl
Algorithm Hash digest
SHA256 ac8b6c563b02ee46d9676252cfb07fac384baad51f97d3cb9f29a18139d06b43
MD5 4bc2e5c2d89376e5ff56dfc80d4de294
BLAKE2b-256 537009b877fb3effc98ed7ee808ce68cfe744b36fbafd9c71c7c4f2bffc90950

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.10.0-cp312-cp312-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 afac90b8b9936ba77b4a6c8cf379978f73ab93e13b2f18e4c1bfa6e93b2e5c9c
MD5 eab3754ca477c7c9e7873a4d276abb00
BLAKE2b-256 f5d33e346c2373514c4d29ac8d9a7928a2133d82f7550677170703f6d14ebc50

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.10.0-cp312-cp312-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 8ccefdcab539f7939b658fa93058a436133631c2de417b75946fde332b95e994
MD5 3ffaadbac628eec2aee895664066ad6f
BLAKE2b-256 82cb6b012d372b2b93f5aeb656d1eef47702d8785304abb434f6b5a023111a92

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.10.0-cp311-cp311-manylinux_2_34_x86_64.whl
Algorithm Hash digest
SHA256 f1b7840c0839e06d1a962dd971090ea2885000729ad34c75914b04c7101dc055
MD5 cdb0cab7fdca36d7c07d43d4ef043e70
BLAKE2b-256 2e15429edbde3dddecaa8665700bc4589563d3c5916e03d027759d2fb4808660

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.10.0-cp311-cp311-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 a771ffad78ef60d07c40390e6ea7580290c95808968c817d6c5c3002e38ecd0a
MD5 978d7deaffa033c82dedb804ff4b0fd7
BLAKE2b-256 063c9a25718de46163e71a12361735517f12b62d2c2dcbcd7ae138e444b3ff21

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.10.0-cp311-cp311-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 65b094dc3029e63b7e402f2d5e9e8d7045fd48bd8d67f15f0431afd134373929
MD5 86ebcc65cea2b4cffb5d59287e12cc53
BLAKE2b-256 3104d647389035a552f59a583f6ff4a55a0497eed50089d23a65ce34da09db3c

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.10.0-cp310-cp310-manylinux_2_34_x86_64.whl
Algorithm Hash digest
SHA256 5d282e935b24a784d122d1b41fb4fad88db18bc9335d0ec36362e0c428fcfe8e
MD5 d9b7a58a56118f21401ad5bda8dc740d
BLAKE2b-256 a4f1c4ca20a26fbd768f780142b7b2fcfda0c7705fd18712c5078bb800c81801

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.10.0-cp310-cp310-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 7e2f9801bb0ac74c6293ea270efe0a044cf55f3da959da2fc6ae2d7303016c7d
MD5 04349c51f7bcbebb079b4099e396cd08
BLAKE2b-256 eada859d4ef3208b28b204061c13d2199dfa5d3c8fdf5143236456f396eb145b

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.10.0-cp310-cp310-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 995d77f84f90cf2ae4e0a7a89bf1e56b162a2db02aabc3f82a0563994ff66e1c
MD5 e8fb8c6331df437ee1e62e0fc237eafc
BLAKE2b-256 624d264779c2611ff34994c6be7de3cdca3f15a3639e55174bbdb3509b666d04

See more details on using hashes here.

Release history Release notifications | RSS feed

This release

0.10.0 This release

13 files

0.9.2

13 files

0.9.1

13 files

0.9.0

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