Install & Compatibility
Where this runs
tested against v0.7.6 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.10
✕ build_error
✓ 3.7s
py 3.11
✕ build_error
✓ 3.4s
py 3.12
✕ build_error
✓ 3.4s
py 3.13
✕ build_error
✕ build_error
py 3.9
✕ build_error
✓ 4.3s
98MB installed
● package 98MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Index
✓ import hnswlib
index = hnswlib.Index(space='l2', dim=128)
The `chroma-hnswlib` package provides the `hnswlib` module for direct use, mimicking the upstream hnswlib API.
This quickstart demonstrates how to initialize an HNSW index, add random 128-dimensional vectors to it, and then perform an approximate k-nearest neighbor search. Key parameters like `ef_construction` and `M` are set during index initialization to tune performance and accuracy.
import hnswlib
import numpy as np
dim = 128
num_elements = 10000
# Generate random data
data = np.float32(np.random.random((num_elements, dim)))
data_labels = np.arange(num_elements)
# Initialize and configure the index
# 'l2' for Euclidean distance, 'ip' for inner product, 'cosine' for cosine similarity
index = hnswlib.Index(space='l2', dim=dim)
index.init_index(max_elements=num_elements, ef_construction=200, M=16)
# Add elements to the index
index.add_items(data, data_labels)
# Perform a search
num_queries = 5
query_data = np.float32(np.random.random((num_queries, dim)))
k = 10 # Number of nearest neighbors to return
labels, distances = index.knn_query(query_data, k=k)
print("Query Results (labels, distances):")
for i in range(num_queries):
print(f" Query {i}: {labels[i]}, {distances[i]}")
Debug
Known issues
breakingDirect installation fails for Python 3.13 due to a lack of pre-built wheels and potential compilation issues. Additionally, there are no pre-built wheels for Python 3.12 on Windows.fixUse Python versions up to 3.12. On Windows for Python 3.12, or for Python 3.13 on any OS, you may need to compile from source, which requires C++ build tools.
affects: 0.7.x (Python 3.13+)
gotchaBuilding `chroma-hnswlib` from source (e.g., if a wheel is not available for your OS/Python version, or using `--no-binary`) requires C++ build tools (e.g., Microsoft Visual C++ 14.0 or greater on Windows). This can lead to build errors if dependencies are not met.fixEnsure that the necessary C++ compiler and build tools are installed and configured on your system before attempting a source build. For Windows, install 'Microsoft C++ Build Tools'.
affects: All versions
gotchaFor maximum performance, especially leveraging Advanced Vector Extensions (AVX) if your hardware supports it, you may need to force recompilation of the library by installing with `--no-binary chroma-hnswlib`. Pre-built wheels are compiled for broader compatibility and might not use AVX.fixUninstall the pre-built version if present (`pip uninstall chroma-hnswlib`) and then reinstall with `pip install --no-binary chroma-hnswlib`.
affects: All versions
gotchaHNSWlib's memory usage is typically higher compared to some other Approximate Nearest Neighbor (ANN) libraries because it needs to store the graph structure in memory, which scales with the number of elements and the `M` parameter.fixMonitor memory consumption, especially with large datasets or high `M` values. Adjust `M` or consider on-disk solutions for extremely large datasets.
affects: All versions
gotchaOptimal performance (trade-off between query speed, index build time, and recall) depends on tuning parameters like `M`, `ef_construction`, and `ef_search`. Incorrect settings can lead to poor search accuracy or slow operations.fixExperiment with different parameter values based on your dataset size, dimensionality, and performance requirements. Higher `M` and `ef_construction` generally improve recall at the cost of slower build/higher memory. Higher `ef_search` improves recall at the cost of slower queries.
affects: All versions
Errors
Common errors & fixes
ERROR: Failed building wheel for chroma-hnswlib
This error typically occurs during installation when the C++ component of chroma-hnswlib cannot be compiled, often due to missing C++ build tools, Python development headers, or an incompatible Python version on the system.
fixEnsure you have the necessary build tools for your operating system:
- On Windows: Install 'Desktop development with C++' workload via Visual Studio Build Tools.
- On Ubuntu/Debian: Run `sudo apt-get install build-essential python3-dev`.
- On macOS: Run `xcode-select --install`.
Also, verify that your Python version is compatible with the version of `chromadb` you are installing, as `chroma-hnswlib` is a core dependency. Sometimes setting the environment variable `HNSWLIB_NO_NATIVE=1` before installation can resolve issues: `export HNSWLIB_NO_NATIVE=1 && pip install chromadb` (or `set HNSWLIB_NO_NATIVE=1 && pip install chromadb` on Windows).
AttributeError: type object 'hnswlib.Index' has no attribute 'file_handle_count'
This error arises from a version conflict between `chromadb` and the underlying `hnswlib` (or `chroma-hnswlib`) library, often when `hnswlib` is installed independently or upgraded by another framework, leading to an API mismatch.
fixTo resolve this, ensure only `chromadb` is managing the HNSWlib components. First, uninstall any independently installed `hnswlib`: `pip uninstall hnswlib`. Then, reinstall `chromadb`: `pip install chromadb`. If the issue persists, you may need to downgrade `chromadb` to a version known to be compatible, checking `chromadb`'s documentation for specific version requirements.
ModuleNotFoundError: No module named 'chromadb'
Although this error explicitly mentions 'chromadb', it is frequently encountered when `chromadb` (which depends on `chroma-hnswlib`) fails to install completely due to underlying `chroma-hnswlib` build issues, or if `chromadb` was simply not installed.
fixFirst, ensure you have attempted to install `chromadb` using `pip install chromadb`. If the installation fails with a 'Failed building wheel for chroma-hnswlib' error, refer to the troubleshooting steps for that error (see above entry) to install the necessary build tools and Python development headers for your system.
Upgrade
Version history
0.7.6latest on PyPI · released Jul 22, 2024
Audit
Dependencies
pythonrequiredPython bindings for the C++ library. Compatible with Python versions ~3.10 to <3.13.
numpyrequiredCommonly used for handling vector data with HNSWlib.
C++ Build ToolsoptionalRequired for compiling from source if pre-built wheels are unavailable or if --no-binary is used (e.g., Microsoft Visual C++ 14.0+ on Windows).