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.7.1.tar.gz (673.8 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.7.1-cp313-cp313-manylinux_2_34_x86_64.whl (981.9 kB view details)

Uploaded CPython 3.13manylinux: glibc 2.34+ x86-64

kannolo-0.7.1-cp313-cp313-macosx_11_0_arm64.whl (793.5 kB view details)

Uploaded CPython 3.13macOS 11.0+ ARM64

kannolo-0.7.1-cp313-cp313-macosx_10_12_x86_64.whl (898.9 kB view details)

Uploaded CPython 3.13macOS 10.12+ x86-64

kannolo-0.7.1-cp312-cp312-manylinux_2_34_x86_64.whl (981.9 kB view details)

Uploaded CPython 3.12manylinux: glibc 2.34+ x86-64

kannolo-0.7.1-cp312-cp312-macosx_11_0_arm64.whl (793.5 kB view details)

Uploaded CPython 3.12macOS 11.0+ ARM64

kannolo-0.7.1-cp312-cp312-macosx_10_12_x86_64.whl (898.8 kB view details)

Uploaded CPython 3.12macOS 10.12+ x86-64

kannolo-0.7.1-cp311-cp311-manylinux_2_34_x86_64.whl (981.9 kB view details)

Uploaded CPython 3.11manylinux: glibc 2.34+ x86-64

kannolo-0.7.1-cp311-cp311-macosx_11_0_arm64.whl (799.3 kB view details)

Uploaded CPython 3.11macOS 11.0+ ARM64

kannolo-0.7.1-cp311-cp311-macosx_10_12_x86_64.whl (905.6 kB view details)

Uploaded CPython 3.11macOS 10.12+ x86-64

kannolo-0.7.1-cp310-cp310-manylinux_2_34_x86_64.whl (981.5 kB view details)

Uploaded CPython 3.10manylinux: glibc 2.34+ x86-64

kannolo-0.7.1-cp310-cp310-macosx_11_0_arm64.whl (798.9 kB view details)

Uploaded CPython 3.10macOS 11.0+ ARM64

kannolo-0.7.1-cp310-cp310-macosx_10_12_x86_64.whl (904.4 kB view details)

Uploaded CPython 3.10macOS 10.12+ x86-64

File details

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

File metadata

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

File hashes

Hashes for kannolo-0.7.1.tar.gz
Algorithm Hash digest
SHA256 489f40f19f3d682564460ac2a286947cf08dc90dc5491a7e971a168964199e29
MD5 55c8f904008d81e02cef662645a3568b
BLAKE2b-256 eb67ab23121623081797df7e70b64a0c5c3e7d793c899d06a526a941cedeb525

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.7.1-cp313-cp313-manylinux_2_34_x86_64.whl
Algorithm Hash digest
SHA256 b9bbcf6303fa3cad940eafe1efd8dc857e10b4a69bf70d4807b17e2c5231753f
MD5 d92711be63216a658b80771e435819f6
BLAKE2b-256 cc5af6d36734bd7bb7ea0254c86b21c8e1b45ef6d3209d081503085a72943f7e

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.7.1-cp313-cp313-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 ed49472cf94357b095f913747059965dedfc2c356f95d64f8d3a98a6f71e90b3
MD5 02249df2d6879570be96501e14127a8f
BLAKE2b-256 a8507217b7dd22d03b795bf0acb890f6bc53d978e187144ed971e32824ca7181

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.7.1-cp313-cp313-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 0f10155bbdb76bdd4dde1768c8bd74b01b92fe3e081812ddacc14385cd10ae63
MD5 29261b3d4497276e3026b41a728d8449
BLAKE2b-256 4a2ae0f2ede5e3d44567aad90d54ee686d3d45b51ef3ba0c0bb5aaf035d29c09

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.7.1-cp312-cp312-manylinux_2_34_x86_64.whl
Algorithm Hash digest
SHA256 0360c70d7277644839cfb1f77748f6a3be252a85df17092ad4bc749837618475
MD5 862b7ffb76bc3beb9fae2f54f077d826
BLAKE2b-256 ed83c4caef103915945fbaafa34bf73330f8747c704e7e9c7a56bf9e9975c05a

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.7.1-cp312-cp312-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 5c65ce80bf4073f36c31292efb7984422e1843328c753ff3053d3ff8f8f87209
MD5 bba4805fb4beca9be154cda1da643cc8
BLAKE2b-256 29634f79ce04010f0603427a7232360a7953a37014f6703ad97fad9b294e8768

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.7.1-cp312-cp312-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 ddfa506519b6bdab84d2464749167e9cdd53661b0570edfe60a91e9206122152
MD5 f174f6de10ff125af693b69bbd57fa60
BLAKE2b-256 b3a3a933577a21d5693a0e14a5f739e63f7e791e5cab440b368c6e474fa04200

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.7.1-cp311-cp311-manylinux_2_34_x86_64.whl
Algorithm Hash digest
SHA256 c2beb57f8e60e9f8b287d49d70b452a18e8e69f8aa5a1875dfc9940e35ef7cfb
MD5 c8d5a01ad207e0a94daa723e1fd8c0eb
BLAKE2b-256 1281d18fee60c02e835b8461728d732b28c864f94c2b7bc71b3f4009cb5a86d1

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.7.1-cp311-cp311-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 ddd82190cfeef268aef9eadf7262034ca2fb3591f7d35521b619223e5139abfe
MD5 0623e7a90f53cb80131dc49ae3fae054
BLAKE2b-256 be08c83bff9086daceab35fd918d3e3b0013b092bffe0966e1d8d8e66bf29e2e

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.7.1-cp311-cp311-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 2e4c4b342fefb26edf179527fb61320790ce7671624ddaff24cf7f8a0ec9f29c
MD5 53d11d4ac9bc4be79ef97f012fbc08aa
BLAKE2b-256 bfc3602867e8e525698fc02a6b036e8949ab9ad804ec4ebfdcb346a421913d8b

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.7.1-cp310-cp310-manylinux_2_34_x86_64.whl
Algorithm Hash digest
SHA256 74383710af4a727a247204ff67671cee10270bc2eb549232f0d7c713dd677fae
MD5 b1ef2838e7d5c0bcd72cc344727cc779
BLAKE2b-256 27c02db13ede1031dbea9a772ab68d717316eb8c306087d451995edcbdf1ddc9

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.7.1-cp310-cp310-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 840800965adf29b17f140addafed317b08d088cfa435cfc6e6fdba83a3fb04a2
MD5 55ee7c35f6eb03e27cc19380e1fef061
BLAKE2b-256 137f75b5737d03ec426b354c2b07e2d97311c5e791d3de7bdd9c2836155e6bf2

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.7.1-cp310-cp310-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 69489d762b09eb439dbc61997807c5afbc59c12d0255a4522e8e61750f141be6
MD5 2e1c543e88636d0165ae9882914969df
BLAKE2b-256 0db40473ccd887d61a755e2a52c5fa7630211f67f2a075ea92bdc3204e1d4730

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

0.8.0

13 files

This release

0.7.1 This release

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