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.2.tar.gz (712.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.9.2-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.2-cp313-cp313-macosx_11_0_arm64.whl (892.8 kB view details)

Uploaded CPython 3.13macOS 11.0+ ARM64

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

Uploaded CPython 3.13macOS 10.12+ x86-64

kannolo-0.9.2-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.2-cp312-cp312-macosx_11_0_arm64.whl (893.1 kB view details)

Uploaded CPython 3.12macOS 11.0+ ARM64

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

Uploaded CPython 3.12macOS 10.12+ x86-64

kannolo-0.9.2-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.2-cp311-cp311-macosx_11_0_arm64.whl (898.8 kB view details)

Uploaded CPython 3.11macOS 11.0+ ARM64

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

Uploaded CPython 3.11macOS 10.12+ x86-64

kannolo-0.9.2-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.2-cp310-cp310-macosx_11_0_arm64.whl (899.1 kB view details)

Uploaded CPython 3.10macOS 11.0+ ARM64

kannolo-0.9.2-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.2.tar.gz.

File metadata

  • Download URL: kannolo-0.9.2.tar.gz
  • Upload date:
  • Size: 712.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.9.2.tar.gz
Algorithm Hash digest
SHA256 21378388ebdeb75876f3269468acab8ea0c644ffa6a7c2fb81867e9dadbd746b
MD5 c59235ccde40819828a4cf3ffbdfa073
BLAKE2b-256 29fbd58d6c52b8675d5cc332c337b6e22920c6e49d51d6de8ee0f5e44f747a72

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.9.2-cp313-cp313-manylinux_2_34_x86_64.whl
Algorithm Hash digest
SHA256 b5b8b9d93ec31c04962aa54b347275b1feaae3d73c785ba5fb1a87ad0a52b0ac
MD5 435ae13402462a430992ea08107f0fd3
BLAKE2b-256 96c3e54c1b9ccf6566f0588119f74bfcc01493884c52dc3df81ba87ff585256f

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.9.2-cp313-cp313-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 f137a295fb115bc03ad60ec9907c578f9554616fc603633baded445ad8ff7367
MD5 eb26dd272f67ca905fab04c9260c8183
BLAKE2b-256 01307cc63378c414def36786384b55efdeffc1a6e04133e04502ddbb6408427e

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.9.2-cp313-cp313-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 5b285c7cd5b94cb4d0dcff5bb323305c6253b1974510a3c2ebab0ec34b5dc299
MD5 024553a7ffca697574ff40381f5d297f
BLAKE2b-256 e32863963d68f16633f3d2f79f696a9bcb721c053c9e98b6b479866c83a39ece

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.9.2-cp312-cp312-manylinux_2_34_x86_64.whl
Algorithm Hash digest
SHA256 153ec3aa84d7d2f065762b3a9687b4ffaecb375ffce20c572f85b51b64163b34
MD5 fbff6eecbaa0d4295096636dbe495f1f
BLAKE2b-256 95bd679433237c8bfa62f12480da11eccfbe4bf8df7606e467df84a84eccb6d3

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.9.2-cp312-cp312-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 ce6851a7294ad251d0bab029704fbd285360867e2a67f92863991d37f6ba05dd
MD5 7422f08f8f5382e8332b25716cc6b236
BLAKE2b-256 70d685393ff286b964c3aad63ffc7dc25df95f08586c2698e14bda8d56745374

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.9.2-cp312-cp312-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 acff69e2735b4bb21972fc255441f5e6e093643fdc5f6f5553e9c53920487d93
MD5 3e7d0724c3b326caa57cf841ac158944
BLAKE2b-256 fa0a2e78ead09ef30aa5aefbd4bcb81556c3d7a89bbe6f552578da2b38242a52

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.9.2-cp311-cp311-manylinux_2_34_x86_64.whl
Algorithm Hash digest
SHA256 5b33d6a8efdb6c9fb273b253babdd3724206e603fc9caa9ad9c4dbcf33e5bf34
MD5 8fbffec3d23e672e36f10e0b4cdfcd87
BLAKE2b-256 bf2ebd126f4251c2e9a3968a49dcd258c434747b0be0d66f7830e2f1a85d972b

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.9.2-cp311-cp311-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 30d39225316b0b870973bb9b6bf076fe810ad0ca01e719779331d268edfc9012
MD5 ec6f10e7a32ffd37467bd3e2856f3db6
BLAKE2b-256 d44bb31c89eac6907c27b2c41d69a8c39281303e88b034901fe5c06a01aa2d22

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.9.2-cp311-cp311-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 a8d49b5adf89c2257a57a253e3b7cfbcc4bd655855d24d6e972acc6380b48c4e
MD5 fb22b5382eed1649649af4212f64935d
BLAKE2b-256 cc52cded5faecb83400cd8c08ada1420fadfefce3ff736bc53035cf90f280e00

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.9.2-cp310-cp310-manylinux_2_34_x86_64.whl
Algorithm Hash digest
SHA256 44390a8dbd60c1d0d948df2819287bbd8c5a21e8c285653f3487487ff6f90aa9
MD5 98bdaf667e902bd84e8023103fd079e9
BLAKE2b-256 773c0d775c8d05be52a60fa1dcbba07f0bc435d56c6588c41a4db0d47e022b19

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.9.2-cp310-cp310-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 135b2665d24b67490b23eedbf84a4a7a833f75e0a00ade2234d6de56b7c15e8c
MD5 d94ea5112ce1722d8432e73419af87ff
BLAKE2b-256 3a0c53a112c9d4a908fe48070a1d4ba1a2c19ed93a9d790852010a52bd59e59f

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kannolo-0.9.2-cp310-cp310-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 c5a95f9b665dbb7e317773b3d88f2aa8c95eaf6bd09a648f38d812e640362b2c
MD5 771aa19c8f18cb7624eeda9f6297a1df
BLAKE2b-256 146e65c9aa73024916523dd9f6abed974af990b90a7c9a919678342bdaf3258f

See more details on using hashes here.

Release history Release notifications | RSS feed

0.10.0

13 files

This release

0.9.2 This release

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