{"id":1963,"library":"chroma-hnswlib","title":"Chroma HNSWlib","description":"Chroma HNSWlib is a Python library that serves as Chroma's fork of the highly efficient HNSW (Hierarchical Navigable Small World) C++ library for fast approximate nearest neighbor (ANN) search. It provides Python bindings to the C++ implementation, enabling high-performance vector similarity search capabilities often used as an underlying component for vector databases like ChromaDB. The current version is 0.7.6, and releases are automated via GitHub actions upon new version tags.","status":"active","version":"0.7.6","language":"en","source_language":"en","source_url":"https://github.com/chroma-core/hnswlib","tags":["vector search","approximate nearest neighbor","HNSW","embedding","ChromaDB","similarity search"],"install":[{"cmd":"pip install chroma-hnswlib","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Python bindings for the C++ library. Compatible with Python versions ~3.10 to <3.13.","package":"python","optional":false},{"reason":"Commonly used for handling vector data with HNSWlib.","package":"numpy","optional":false},{"reason":"Required 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).","package":"C++ Build Tools","optional":true}],"imports":[{"note":"The `chroma-hnswlib` package provides the `hnswlib` module for direct use, mimicking the upstream hnswlib API.","symbol":"Index","correct":"import hnswlib\nindex = hnswlib.Index(space='l2', dim=128)"}],"quickstart":{"code":"import hnswlib\nimport numpy as np\n\ndim = 128\nnum_elements = 10000\n\n# Generate random data\ndata = np.float32(np.random.random((num_elements, dim)))\ndata_labels = np.arange(num_elements)\n\n# Initialize and configure the index\n# 'l2' for Euclidean distance, 'ip' for inner product, 'cosine' for cosine similarity\nindex = hnswlib.Index(space='l2', dim=dim)\nindex.init_index(max_elements=num_elements, ef_construction=200, M=16)\n\n# Add elements to the index\nindex.add_items(data, data_labels)\n\n# Perform a search\nnum_queries = 5\nquery_data = np.float32(np.random.random((num_queries, dim)))\nk = 10 # Number of nearest neighbors to return\n\nlabels, distances = index.knn_query(query_data, k=k)\n\nprint(\"Query Results (labels, distances):\")\nfor i in range(num_queries):\n    print(f\"  Query {i}: {labels[i]}, {distances[i]}\")","lang":"python","description":"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."},"warnings":[{"fix":"Use 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.","message":"Direct 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.","severity":"breaking","affected_versions":"0.7.x (Python 3.13+)"},{"fix":"Ensure 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'.","message":"Building `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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Uninstall the pre-built version if present (`pip uninstall chroma-hnswlib`) and then reinstall with `pip install --no-binary chroma-hnswlib`.","message":"For 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Monitor memory consumption, especially with large datasets or high `M` values. Adjust `M` or consider on-disk solutions for extremely large datasets.","message":"HNSWlib'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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Experiment 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.","message":"Optimal 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}