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.1.tar.gz (709.6 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.1-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.1-cp313-cp313-macosx_11_0_arm64.whl (899.8 kB view details)

Uploaded CPython 3.13macOS 11.0+ ARM64

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

Uploaded CPython 3.13macOS 10.12+ x86-64

kannolo-0.9.1-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.1-cp312-cp312-macosx_11_0_arm64.whl (900.0 kB view details)

Uploaded CPython 3.12macOS 11.0+ ARM64

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

Uploaded CPython 3.12macOS 10.12+ x86-64

kannolo-0.9.1-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.1-cp311-cp311-macosx_11_0_arm64.whl (906.7 kB view details)

Uploaded CPython 3.11macOS 11.0+ ARM64

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

Uploaded CPython 3.11macOS 10.12+ x86-64

kannolo-0.9.1-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.1-cp310-cp310-macosx_11_0_arm64.whl (906.7 kB view details)

Uploaded CPython 3.10macOS 11.0+ ARM64

kannolo-0.9.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.9.1.tar.gz.

File metadata

  • Download URL: kannolo-0.9.1.tar.gz
  • Upload date:
  • Size: 709.6 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.1.tar.gz
Algorithm Hash digest
SHA256 51188ce064adbab64f59b021cd4c7904c67a222e3da2e4a68ca3eccad4404454
MD5 3a27efe91e6afabde230894fa9cefa1b
BLAKE2b-256 fadb76b8639b976daf3742fc1e14c824af3912c601136dc06b2d2fef6e07edae

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.9.1-cp313-cp313-manylinux_2_34_x86_64.whl
Algorithm Hash digest
SHA256 40752b42e74ad60cd822ed2da58ad73c763072b40c2ec21d79fe0452205caa79
MD5 16013d32fc173d833fc7739c0e046b54
BLAKE2b-256 8b5ec82b639427da8d003d002da0450cedd174d7b53416ed0bff8c47d3057ec1

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.9.1-cp313-cp313-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 187a7cba3afe4a149c7f322469902bdfe46c81386112fce050e6da7d2dd973f2
MD5 6801a27aa88c431400b52b3a52a34517
BLAKE2b-256 c963f7178ca6159b4f46842c27f0718c5b44921ab517f53ee83f24bae49fd967

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.9.1-cp313-cp313-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 8f4ac9976c8ce5a4cfdc161036c300c952db96865d95dd70ab8c40b17d0f5868
MD5 18e1866f4929732f473191a6734263ef
BLAKE2b-256 495fab6a53dd23efaa1339d6e0209e25725ee5d6b085bce561d5144516fc2a09

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.9.1-cp312-cp312-manylinux_2_34_x86_64.whl
Algorithm Hash digest
SHA256 b5d68168a0f986a6173a51ccda2de2c1bff25b35184e1e24640757f49fea586c
MD5 d4edb0fbd76c93cf92cd3995b013581f
BLAKE2b-256 dca1910982800f6cced94a2b86f5e11b3ecdb840f778c88b1b56ad725e5e7c4c

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.9.1-cp312-cp312-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 8d5594c77fa1b03fa2ee32cd412d5904179df86db0806bf00d811bc50d30c889
MD5 e6f4f8cd231c40fad25d5ddf6fb3f51f
BLAKE2b-256 cadb73a2b500d23d866f89cd8d6b137963b783c7f3d32eaeaa572ab7941e5e90

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.9.1-cp312-cp312-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 35dcb548a00b5b5e9262f9009cb5ea05fefdc360bb7f7980eb070ebfc0b7b732
MD5 90fd1469af357304ad032f463d6d95ed
BLAKE2b-256 0d47d714c2f0ac372fbed1434fdad8a95f06d2d1203a51cfd2e5937edb67b03f

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.9.1-cp311-cp311-manylinux_2_34_x86_64.whl
Algorithm Hash digest
SHA256 ccf09e003cb8f5be62b577f021c72f19851b659ea6d5f5bced9d15a4e2fa75e1
MD5 5050fd543dab66d11e734ca14b5298ef
BLAKE2b-256 f83908f65d0e72ffbcbe6d74f531c0ea22059dca1a7e054f0b79f46959190235

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.9.1-cp311-cp311-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 549ddd50073c06a0bb58e16a7f0dbce10c2cc12146e7dd2910e94127000d73f3
MD5 e5276ebe206e5e83dee7c8981057154a
BLAKE2b-256 365dcefca1dc7ded38b0d9f95442e701e2551fe9569d52fb35a5995f6192133d

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.9.1-cp311-cp311-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 e8890dd1c63872cc4eae610f6a8f729bd8d7982b46232b9725b68f48f35155a7
MD5 9d544bf83f90771325cbd584cd7a62d8
BLAKE2b-256 6cee17e841fc99a98a98bca05dda7fe6ba57c03da73a9a40529ca55e39f77ed2

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.9.1-cp310-cp310-manylinux_2_34_x86_64.whl
Algorithm Hash digest
SHA256 277e60466e0afc75aa6b02f84f9b89c2636fb5b1392b654d4854f874e7be816a
MD5 b5a1722f32e1be01200cf49c30fc9997
BLAKE2b-256 d901f4661c5df3ab7f7e55514dc609545e0e4ca2ee111414381db605e8b03918

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.9.1-cp310-cp310-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 124902fc5f79208bea303bc103fc9457a4cb54d9afb947a00b67a1f73cd5e3d0
MD5 abdaf47d11be2b9285aad607343800ca
BLAKE2b-256 c04359005a348acea7ce25700ce15a631969706a105bcf3e9d7ebf749879bc3a

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.9.1-cp310-cp310-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 939004889032b712a2491ea049197e53213ae2ee084a185b54e390b3e0ef8eeb
MD5 70ffd67f0bf737b2624c928173665cf2
BLAKE2b-256 e334d14c66c9fc53e16ced80cdf5670b21ca3e6e6174653a9f389cdf40e88ea5

See more details on using hashes here.

Release history Release notifications | RSS feed

0.10.0

13 files

0.9.2

13 files

This release

0.9.1 This release

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