Skip to main content

pyhnsw - Python Bindings for HNSW

Fast approximate nearest neighbor search using Hierarchical Navigable Small World (HNSW) graphs.

Features

  • Fast: hand-written SIMD distance kernels (AVX2/FMA, SSE2, scalar) picked at runtime; no external dependencies
  • Simple: Clean Python API similar to popular ANN libraries
  • Flexible: Supports both L2 and cosine distance metrics
  • Efficient: Batch operations for adding and searching multiple vectors
  • Type Support: Both single (float32) and double (float64) precision

Installation

From Source

First, ensure you have the required dependencies:

pip install numpy pybind11

Then build and install the package:

cd bindings/pyhnsw
pip install .

Build with CMake (Alternative)

cd bindings/pyhnsw
mkdir build && cd build
cmake ..
make

Quick Start

import numpy as np
import pyhnsw

# Create an index for 128-dimensional vectors
index = pyhnsw.HNSW(dim=128, M=16, ef_construction=200, ef_search=100, metric="l2")

# Generate some random data
data = np.random.randn(10000, 128).astype(np.float32)

# Add vectors to the index
index.add_items(data)

# Search for nearest neighbors
query = np.random.randn(128).astype(np.float32)
indices, distances = index.search(query, k=10)

print(f"Found {len(indices)} nearest neighbors")
print(f"Indices: {indices}")
print(f"Distances: {distances}")

API Reference

HNSW Class

pyhnsw.HNSW(dim, M=16, ef_construction=200, ef_search=100, metric="l2")

Creates a new HNSW index.

Parameters:

  • dim (int): Dimensionality of the vectors
  • M (int): Maximum number of connections per element (default: 16)
  • ef_construction (int): Size of the dynamic candidate list during construction (default: 200)
  • ef_search (int): Size of the dynamic candidate list during search (default: 100)
  • metric (str): Distance metric to use ('l2' or 'cosine', default: 'l2')

Methods

add_item(vec)

Add a single vector to the index.

Parameters:

  • vec (numpy.ndarray): 1D array of shape (dim,) containing the vector

add_items(data)

Add multiple vectors to the index.

Parameters:

  • data (numpy.ndarray): 2D array of shape (n_items, dim) containing the vectors

search(query, k=10)

Search for k nearest neighbors of a query vector.

Parameters:

  • query (numpy.ndarray): 1D array of shape (dim,) containing the query vector
  • k (int): Number of nearest neighbors to return (default: 10)

Returns:

  • indices (numpy.ndarray): 1D array of shape (k,) containing the indices of nearest neighbors
  • distances (numpy.ndarray): 1D array of shape (k,) containing the distances to nearest neighbors

batch_search(queries, k=10)

Search for k nearest neighbors of multiple query vectors.

Parameters:

  • queries (numpy.ndarray): 2D array of shape (n_queries, dim) containing the query vectors
  • k (int): Number of nearest neighbors to return (default: 10)

Returns:

  • indices (numpy.ndarray): 2D array of shape (n_queries, k) containing the indices
  • distances (numpy.ndarray): 2D array of shape (n_queries, k) containing the distances

size()

Get the number of items in the index.

dim()

Get the dimensionality of vectors in the index.

Examples

Using Cosine Similarity

import numpy as np
import pyhnsw

# Create index with cosine metric
index = pyhnsw.HNSW(dim=512, metric="cosine")

# For cosine similarity, it's recommended to normalize vectors
data = np.random.randn(1000, 512).astype(np.float32)
data = data / np.linalg.norm(data, axis=1, keepdims=True)

index.add_items(data)

# Search with normalized query
query = np.random.randn(512).astype(np.float32)
query = query / np.linalg.norm(query)

indices, distances = index.search(query, k=5)

Batch Processing

import numpy as np
import pyhnsw

# Create index
index = pyhnsw.HNSW(dim=256)

# Add data in batches
batch_size = 1000
for i in range(0, 10000, batch_size):
    batch = np.random.randn(batch_size, 256).astype(np.float32)
    index.add_items(batch)

# Batch search
queries = np.random.randn(100, 256).astype(np.float32)
indices, distances = index.batch_search(queries, k=20)

# Process results
for i, (idx, dist) in enumerate(zip(indices, distances)):
    print(f"Query {i}: Found {len(idx)} neighbors")

Double Precision

import numpy as np
import pyhnsw

# Use HNSWDouble for float64 precision
index = pyhnsw.HNSWDouble(dim=128)

# Use float64 arrays
data = np.random.randn(1000, 128).astype(np.float64)
index.add_items(data)

query = np.random.randn(128).astype(np.float64)
indices, distances = index.search(query, k=10)

Performance Tips

  1. Parameter Tuning:

    • Increase M for better recall at the cost of memory and construction time
    • Increase ef_construction for better index quality at the cost of construction time
    • Increase ef_search for better search recall at the cost of search time
  2. Batch Operations:

    • Use add_items() instead of multiple add_item() calls
    • Use batch_search() for multiple queries
  3. Data Preprocessing:

    • Normalize vectors when using cosine similarity
    • Use float32 for better performance unless you need double precision

Testing

Run the test suite:

python test_pyhnsw.py

Dependencies

  • Python >= 3.9
  • NumPy >= 1.19.0
  • pybind11 >= 2.6.0
  • C++17 compatible compiler

License

See the main project LICENSE file.

Metadata

Release files for pyhnsw 0.2.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pyhnsw 0.2.3
File Size Uploaded Provenance Actions
pyhnsw-0.2.3.tar.gz 19.6 kB With provenance Details for pyhnsw-0.2.3.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for pyhnsw 0.2.3
File Actions
pyhnsw-0.2.3-cp312-cp312-win_amd64.whl CPython 3.12 CPython 3.12 Windows x86-64 Details for pyhnsw-0.2.3-cp312-cp312-win_amd64.whl
pyhnsw-0.2.3-cp312-cp312-musllinux_1_1_x86_64.whl CPython 3.12 CPython 3.12 Linux musl 1.1+ x86-64 Details for pyhnsw-0.2.3-cp312-cp312-musllinux_1_1_x86_64.whl
pyhnsw-0.2.3-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl CPython 3.12 CPython 3.12 Linux glibc 2.28+ x86-64, Linux glibc 2.27+ x86-64 Details for pyhnsw-0.2.3-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
pyhnsw-0.2.3-cp311-cp311-win_amd64.whl CPython 3.11 CPython 3.11 Windows x86-64 Details for pyhnsw-0.2.3-cp311-cp311-win_amd64.whl
pyhnsw-0.2.3-cp311-cp311-musllinux_1_1_x86_64.whl CPython 3.11 CPython 3.11 Linux musl 1.1+ x86-64 Details for pyhnsw-0.2.3-cp311-cp311-musllinux_1_1_x86_64.whl
pyhnsw-0.2.3-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl CPython 3.11 CPython 3.11 Linux glibc 2.27+ x86-64, Linux glibc 2.28+ x86-64 Details for pyhnsw-0.2.3-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
pyhnsw-0.2.3-cp310-cp310-win_amd64.whl CPython 3.10 CPython 3.10 Windows x86-64 Details for pyhnsw-0.2.3-cp310-cp310-win_amd64.whl
pyhnsw-0.2.3-cp310-cp310-musllinux_1_1_x86_64.whl CPython 3.10 CPython 3.10 Linux musl 1.1+ x86-64 Details for pyhnsw-0.2.3-cp310-cp310-musllinux_1_1_x86_64.whl
pyhnsw-0.2.3-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl CPython 3.10 CPython 3.10 Linux glibc 2.28+ x86-64, Linux glibc 2.27+ x86-64 Details for pyhnsw-0.2.3-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
pyhnsw-0.2.3-cp39-cp39-win_amd64.whl CPython 3.9 CPython 3.9 Windows x86-64 Details for pyhnsw-0.2.3-cp39-cp39-win_amd64.whl
pyhnsw-0.2.3-cp39-cp39-musllinux_1_1_x86_64.whl CPython 3.9 CPython 3.9 Linux musl 1.1+ x86-64 Details for pyhnsw-0.2.3-cp39-cp39-musllinux_1_1_x86_64.whl
pyhnsw-0.2.3-cp39-cp39-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl CPython 3.9 CPython 3.9 Linux glibc 2.28+ x86-64, Linux glibc 2.27+ x86-64 Details for pyhnsw-0.2.3-cp39-cp39-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl

Total release size: 4.0 MB

Release files / pyhnsw-0.2.3.tar.gz

Download URL pyhnsw-0.2.3.tar.gz
Size 19.6 kB
Tags Source
SHA-256 checksum
How to use checksums
3e4f30b75bdca527d93361bffd080b24a5cbb3d2a16684a04bfcba6cb0d67164
BLAKE2b-256 checksum
How to use checksums
14997efae5e231f3f6983a47a52faf8380d3ddbe580021b3670fe0b5c1ec4b4a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 19, 2026.

Transparency log

Release files / pyhnsw-0.2.3-cp312-cp312-win_amd64.whl

Download URL pyhnsw-0.2.3-cp312-cp312-win_amd64.whl
Size 136.5 kB
Tags CPython 3.12 Windows x86-64
SHA-256 checksum
How to use checksums
6c0fe156b75fa4f4be3a948697eff7f4d931887fecd03510633f8adcb71a022b
BLAKE2b-256 checksum
How to use checksums
0fa9a6c1dd9aa28fb6c144eaefab2d498783a7b65997e03e056bfd1322c789fd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 19, 2026.

Transparency log

Release files / pyhnsw-0.2.3-cp312-cp312-musllinux_1_1_x86_64.whl

Download URL pyhnsw-0.2.3-cp312-cp312-musllinux_1_1_x86_64.whl
Size 696.3 kB
Tags CPython 3.12 Linux musl 1.1+ x86-64
SHA-256 checksum
How to use checksums
261dd7f52649e08e1460759955c1a4ec9bf7b6a2209b800604ad474debc3f5b9
BLAKE2b-256 checksum
How to use checksums
3bbc904e46d4879f162a677b50b97aa3225f7c27fa61c3562fcd02e8d45dcb6b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 19, 2026.

Transparency log

Release files / pyhnsw-0.2.3-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl

Download URL pyhnsw-0.2.3-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Size 160.3 kB
Tags CPython 3.12 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
419e7a1c43d48b41c50c9da235efa1a4c06c451b9c2e622ac324119472c0ba5a
BLAKE2b-256 checksum
How to use checksums
e83c4564f4aa245fb09f8d426f8e2425c3de1f7823f6936768b995d22417f2c9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 19, 2026.

Transparency log

Release files / pyhnsw-0.2.3-cp311-cp311-win_amd64.whl

Download URL pyhnsw-0.2.3-cp311-cp311-win_amd64.whl
Size 132.9 kB
Tags CPython 3.11 Windows x86-64
SHA-256 checksum
How to use checksums
170d7d361f945151277cabcda212b4d3c631a342ed9f95ecc7cd04da42df8f22
BLAKE2b-256 checksum
How to use checksums
60b85800c1b1b191566760282b47df441cd0b613675ef81800b79d0a36dc0e61
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 19, 2026.

Transparency log

Release files / pyhnsw-0.2.3-cp311-cp311-musllinux_1_1_x86_64.whl

Download URL pyhnsw-0.2.3-cp311-cp311-musllinux_1_1_x86_64.whl
Size 695.6 kB
Tags CPython 3.11 Linux musl 1.1+ x86-64
SHA-256 checksum
How to use checksums
bf60292945fb07eb9c6f6a8a37ff035f0ae9124b7f40b26610fb4447bb6bc280
BLAKE2b-256 checksum
How to use checksums
e06e49faeaf24b5f6bdbcd2f25fe8b7abae694eae5e3885da32a1f7a237b3da7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 19, 2026.

Transparency log

Release files / pyhnsw-0.2.3-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl

Download URL pyhnsw-0.2.3-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Size 161.0 kB
Tags CPython 3.11 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
d0c0d3cfbb9f132dbfd71c9cffd58db508b796fc48b66da06711f8ae14c53ecd
BLAKE2b-256 checksum
How to use checksums
7d7d485546099451e36a50290f5071344fccc38001dbbb2f21fbb246cf65cb22
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 19, 2026.

Transparency log

Release files / pyhnsw-0.2.3-cp310-cp310-win_amd64.whl

Download URL pyhnsw-0.2.3-cp310-cp310-win_amd64.whl
Size 131.7 kB
Tags CPython 3.10 Windows x86-64
SHA-256 checksum
How to use checksums
4e72f47f65710944c628e976d3b50e1bce24998a50b112e6611d0662a44ffb9e
BLAKE2b-256 checksum
How to use checksums
6b0cb7ae95ed324d9bc018a607b388862dc1d19ce53b5abc158c2af268afd3d4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 19, 2026.

Transparency log

Release files / pyhnsw-0.2.3-cp310-cp310-musllinux_1_1_x86_64.whl

Download URL pyhnsw-0.2.3-cp310-cp310-musllinux_1_1_x86_64.whl
Size 695.2 kB
Tags CPython 3.10 Linux musl 1.1+ x86-64
SHA-256 checksum
How to use checksums
73ac6b013fc2d3caa465c1b7c846f1686439515e755608fd919118afc37c8861
BLAKE2b-256 checksum
How to use checksums
59ca853b8458cea3f46c9e60cef8ea857f830f830f928f6e29e2502d52726440
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 19, 2026.

Transparency log

Release files / pyhnsw-0.2.3-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl

Download URL pyhnsw-0.2.3-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Size 159.6 kB
Tags CPython 3.10 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
9fde451ead1530e39fbb258889a2dfd34365a78c1ddb3c770e58071b070c1772
BLAKE2b-256 checksum
How to use checksums
31c341df6c0b9c5bebdf03a1daad7c41e1e59fe96d36cfafc353e81226d42d27
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 19, 2026.

Transparency log

Release files / pyhnsw-0.2.3-cp39-cp39-win_amd64.whl

Download URL pyhnsw-0.2.3-cp39-cp39-win_amd64.whl
Size 131.8 kB
Tags CPython 3.9 Windows x86-64
SHA-256 checksum
How to use checksums
7985da5a555476f781f1c2827ac851230d95ac5b537e768c2fa310eb59e0f3bf
BLAKE2b-256 checksum
How to use checksums
c037d1dedf844e4168d3d34a815670bfda8bc930475369d6995d9d244408d095
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 19, 2026.

Transparency log

Release files / pyhnsw-0.2.3-cp39-cp39-musllinux_1_1_x86_64.whl

Download URL pyhnsw-0.2.3-cp39-cp39-musllinux_1_1_x86_64.whl
Size 695.4 kB
Tags CPython 3.9 Linux musl 1.1+ x86-64
SHA-256 checksum
How to use checksums
df052f4c1e0ccdcaf4339eb8398f192576c46ee3fbfc672f2267d247082e88c9
BLAKE2b-256 checksum
How to use checksums
ae25dfc1ed3380c97de0aa9b556a524dae88164abeff57f542136877791e220c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 19, 2026.

Transparency log

Release files / pyhnsw-0.2.3-cp39-cp39-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl

Download URL pyhnsw-0.2.3-cp39-cp39-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Size 159.3 kB
Tags CPython 3.9 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
f7c80a05add02de8d720e7bed79fb99b91d7e6c74b98c83c9f2d937a4452a1cc
BLAKE2b-256 checksum
How to use checksums
d5c5a8ef24334fa7c4f03e9859a7d9c62e1fdc18841119e3f80428ff6ccb7b0f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 19, 2026.

Transparency log

Security for pyhnsw 0.2.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

All 13 files in this release have been uploaded with provenance metadata.

Select from 13 files

Attestation for pyhnsw-0.2.3.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 19, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page