Hnswlib is a lightweight, header-only C++ library with Python bindings designed for fast Approximate Nearest Neighbor (ANN) search. It implements the Hierarchical Navigable Small Worlds (HNSW) algorithm, enabling efficient similarity search in high-dimensional vector spaces. The library supports dynamic updates (insertion and deletion of elements) and various distance metrics like L2, Inner Product, and Cosine similarity. Its current stable release on PyPI is 0.8.0, with version 0.9.0 recently released on GitHub, and it maintains a relatively active release cadence.
pip install hnswlibVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to create an HNSW index, initialize it with parameters, add vector data, perform a k-nearest neighbor query, and then save and load the index. It highlights the importance of re-setting the `ef` parameter after loading the index.
Rebuild indices with a supported `hnswlib` version. Consider exporting data and re-importing if migration is critical.
Upgrade to `hnswlib` v0.6.2 or later to prevent corruption of large pickled indices. Rebuild any potentially corrupted indices.
Ensure that the `hnswlib` library is compiled and indices are used on machines with compatible CPU architectures and instruction sets. Recompile without specific AVX flags if maximum portability is needed, or rebuild indices on the target architecture.
Always call `index.set_ef(value)` after loading an index to configure the desired query performance.
Review multi-threaded search logic; if statistic aggregation was implicitly relied upon, evaluate impact. Check release notes for explicit alternatives if available.
Upgrade to `hnswlib` v0.9.0 or later once released on PyPI for correct filter behavior and robust error handling when `k` exceeds available elements.
On Linux, install Python development headers and build tools: `sudo apt-get install python3-dev build-essential`. On Windows, install the 'Desktop development with C++' workload from Visual Studio Build Tools. Alternatively, try `pip install hnswlib --only-binary=:all:` to install pre-built wheels, or use `conda install -c conda-forge hnswlib`.
Reinstall `hnswlib` in a clean virtual environment: first, `pip uninstall hnswlib`, then `pip install hnswlib`. Ensure no other packages are inadvertently shadowing or conflicting with `hnswlib`.
Ensure that only a compatible version of `hnswlib` or `chroma-hnswlib` (if `chromadb` requires it) is installed. A common solution is to uninstall both and let `chromadb` install its required dependency: `pip uninstall hnswlib chromadb chroma-hnswlib` followed by `pip install chromadb`.
Create a new, uninitialized `hnswlib.Index` object and directly call `load_index()` on it with the path to the saved index file. For example: `new_index = hnswlib.Index(space='l2', dim=128); new_index.load_index('saved_index.bin')`.Before adding more elements, dynamically increase the index's capacity using the `resize_index()` method: `index.resize_index(new_size)`, where `new_size` must be greater than the current number of elements plus the new elements to be added.