Hnswlib

Hnswlib is an open-source, header-only C++ implementation of the Hierarchical Navigable Small World (HNSW) algorithm for approximate nearest neighbor search, with Python bindings. It is maintained under the nmslib organization on GitHub and licensed under Apache 2.0. It supports incremental index construction, element updates, and deletions.

What It Is

Hnswlib builds graph-based vector indexes that return the k closest elements to a query vector. The README lists it as lightweight, with no dependencies other than C++11. Interfaces exist for C++ and Python, with external support for Java and R. Python users create an index for a chosen distance space and dimension, initialize it with capacity and graph parameters (M, ef_construction), add numpy vectors with optional integer labels, and run batch k-nearest-neighbor queries that return labels and distances.

Index Operations and Distances

The Python bindings support squared L2, inner product, and cosine distance. Custom user-defined distances are supported in C++. Items can be inserted incrementally, updated by reusing labels, marked as deleted, and later replaced by new items to control index size. Queries can use a filter on labels, and the thread count can be set for insertion and search. Indexes can be saved to and loaded from disk, and Python index objects are picklable. The query-time accuracy/speed trade-off is controlled with the ef parameter.

Recent Releases

The README describes version 0.10.0rc2 as a release candidate, not a stable PyPI upload. It adds an optional no-exceptions C++ API (*NoExceptions methods returning Status/StatusOr) so headers can be compiled with -fno-exceptions, stream-based saveIndex/loadIndex, and CI coverage across Clang, GCC, MSVC, ASAN and UBSAN. Version 0.8.0 added multi-vector document search and epsilon search in C++, and 0.7.0 added filtering and replacement of deleted elements.

Setup Path

Install with pip install hnswlib or build from source with pip install . after cloning the repository. The C++ examples cover multithreaded use, multivector search, epsilon search and filtering. The repository also documents reproducing a 200M SIFT test and an updates test.