hnswlib

What it is and what it does

Hnswlib is a Python binding to a header-only C++ implementation of the Hierarchical Navigable Small World (HNSW) algorithm for fast approximate nearest neighbor search. It lets you build an index of high-dimensional vectors and query them efficiently to find the k nearest neighbors, with support for three distance metrics: squared L2, inner product, and cosine distance. The library is designed for incremental workflows—you can add, update, and delete vectors after index creation, mark elements as deleted without rebuilding, and save/load indexes to disk.

The main dependency is numpy for array handling. Installation requires a C++ compiler because the package compiles a native extension at install time. Once built, it offers thread-safe batch operations for both insertion and querying, with tunable parameters (M and ef_construction) to trade off memory footprint and construction speed against query accuracy. It is commonly used in machine learning and information retrieval pipelines where you need to find similar embeddings or vectors quickly without exhaustive search.

Use it for:

• Build a semantic search engine over document embeddings to find similar texts or documents by vector similarity.
• Implement real-time product recommendation by indexing product embeddings and querying for nearest neighbors to a user's preference vector.
• Create a reverse image search system by indexing image feature vectors and finding visually similar images.
• Deduplicate large datasets by indexing all embeddings and finding near-duplicate vectors within a distance threshold.
• Support incremental machine learning pipelines where new training examples are continuously added to an index for online similarity lookup.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Fast approximate nearest neighbor search using the HNSW algorithm with Python bindings, supporting incremental index construction, updates, and deletions on vector data.

Yes, with conditions. Hnswlib is actively maintained, has no known vulnerabilities, and is popular (571766 monthly downloads). Install it if you need fast approximate nearest neighbor search and can handle the C++ compilation requirement. However, verify the license before use in proprietary contexts, and be aware that the last release was 985 days ago—check whether the current version meets your needs or if you need to build from the active repository.

Install

hnswlib on PyPI

pip install hnswlib

uv add hnswlib

poetry add hnswlib

Installing hnswlib

Before you install

High install friction due to C++ compilation requirement (header-only HNSW implementation). Package is actively maintained with recent commits and a large repository (5309 stars), but the last release was 985 days ago despite ongoing development activity.

License in practice

License treatment is unclear—no SPDX identifier or raw license text is available in the metadata. Verify the actual license before use in proprietary or restricted contexts.

Quickstart

pip install hnswlib
import hnswlib
import numpy as np

index = hnswlib.Index(space='l2', dim=16)
index.init_index(max_elements=100, M=16, ef_construction=200)
data = np.random.random((100, 16))
index.add_items(data, np.arange(100))
labels, distances = index.knn_query(data[:5], k=5)

Requires a C++ compiler and build tools to compile the C++ extension during installation.

Verify before relying

• Whether Python version support is truly unspecified or if there are undocumented minimum/maximum version constraints.
• Current maintenance status and release cadence given the 985-day gap between latest release and active repository commits.
• Whether the package is suitable for production use given the release timing relative to active development.

Package facts

Evidence: hnswlib-0.8.0.tar.gz

Tags

More Scientific/Engineering packages