# NMSLIB: k-NN search for non-metric spaces, and how to install it

> NMSLIB is a C++ similarity search library with Python bindings and a Thrift query server, aimed at generic and non-metric spaces rather than only metric ones. Its HNSW method is the fastest thing in it, but the standalone hnswlib is the better fit when HNSW is all you need.

**nmslib/nmslib** — Non-Metric Space Library (NMSLIB): An efficient similarity search library and a toolkit for evaluation of k-NN methods for generic non-metric spaces.

- Repository: https://github.com/nmslib/nmslib
- Stars: 3,591 · Forks: 461
- Language: C++
- License: Apache-2.0
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/nmslib-nmslib

## What problem NMSLIB solves, and for whom

Most nearest-neighbour libraries assume a metric space: distances obey the triangle inequality, and the index can use that assumption to prune. NMSLIB was built around the opposite case. The README states that the project's main focus is on generic and approximate search methods, in particular methods for non-metric spaces, and calls NMSLIB possibly the first library with principled support for non-metric space searching. That is the niche. If your distance is a learned similarity, an asymmetric divergence, or something that simply does not satisfy the triangle inequality, tree-based indexes that rely on metric axioms will not give you their usual guarantees.

The audience is therefore narrower than a general vector database. It is engineers who have a custom distance and need approximate k-NN over it, and researchers who want to compare several search methods under one harness. The README describes the project as an extendible library, meaning new search methods and distance functions can be added, and notes that the core library has no third-party dependencies. It also lists a query server usable from Java and other languages through Apache Thrift version 0.12, with a native Java client that does not require a C++ library on the machine.

One caveat worth stating early: the repository's most recent release listed is v2.1.1 from 2021-02-03, while the last push to the default branch was on 2026-04-13. The release history and the commit history tell different stories, and the README does not explain the gap.

## How the library is put together: C++ core, Python bindings, Thrift server

The repository layout makes the architecture fairly plain. similarity_search/ holds the C++ core, python_bindings/ wraps it for Python, query_server/ exposes it over Apache Thrift, and sample_standalone_app/ and test_batch_app/ are entry points for using the library without Python. The manual/ directory is where the README says all the documentation lives, including the Python bindings, the query server, the description of methods and spaces, and build instructions.

The method lineup is described in the brief history section. The neighbourhood graph family is represented by the Hierarchical Navigable Small World graph (HNSW) from Malkov and Yashunin. Other named methods include a modification of the VP-tree due to Boytsov and Naidan, the Neighborhood APProximation index (NAPP) proposed by Tellez et al. and improved by David Novak, and a vanilla uncompressed inverted file. Having several families under one API is the point of the evaluation toolkit framing: you can hold the data and the distance fixed and swap the index.

The extension story is the part that actually makes non-metric search practical. A distance function that is not built in has to be added as a new space, which means writing C++ against the library's interfaces rather than passing a Python callable. The README does not document a Python-level way to register an arbitrary distance, so plan for a C++ build step if your distance is unusual.

## Installing NMSLIB and running a first HNSW query in Python

The README advertises binary wheels, so the shortest path is pip. The project provides binaries for Python 3.8 through 3.13, plus 3.14 on Linux, across Linux, macOS and Windows and both Intel and ARM CPUs. If a wheel exists for your interpreter, no compiler is involved.

```bash
pip install nmslib
```

After installation, the import name is nmslib. The README points to the manual page for the Python bindings, which is where the exact init and knnQuery signatures live. The manual is also where the parameter names for each method and space are listed; the README does not reproduce them, so read that page before writing index code.

The README does not give a Python usage example, so there is no snippet to copy here. What it does state is that NMSLIB can be used directly in C++ and Python via Python bindings, and that all documentation including the Python bindings is found on the manual page. Start there for the exact call sequence.

For non-Python callers, the query server is the other route. The README specifies Apache Thrift version 0.12 as the interface, and says the Java client is native, so it runs on many platforms without a C++ library installed. That version pin is worth noticing: Thrift 0.12 is old, and a mismatched Thrift on the client side is a plausible source of trouble that the README does not address.

## Where NMSLIB is the wrong tool

The clearest limitation is scope. NMSLIB is a library, not a service. There is no replication, no persistence layer described in the README, no sharding and no consistency model. If you need a running cluster that survives a node restart, you are looking at the wrong layer; the README's own framing is a library plus an optional Thrift server, and a Thrift server is not a distributed system.

Second, non-metric support is real but not free. The README does not describe a Python API for supplying an arbitrary distance function, so a custom divergence means touching C++ and rebuilding. Teams that want to iterate on a learned distance in a notebook will find that loop slow.

Third, the release cadence is a signal to weigh. The most recent release in the given list is v2.1.1 from 2021-02-03, and v2.0.6 before it in 2020. The repository's last push was on 2026-04-13, so the code has moved since the last tagged release, but anyone pinning to a release is pinning to something from 2021. The README does not document a supported upgrade path between versions, and the changelog for v2.0.5 is described only as removing old code and providing binary wheels. Verify wheel availability for your interpreter before you plan around a pip install, because the documented binary matrix is a hard boundary, not a suggestion.

Finally, if your space is metric and your method is HNSW, NMSLIB is carrying weight you do not need. The README itself points to hnswlib as a standalone header-only implementation of the same method.

## NMSLIB vs Faiss and hnswlib: what actually differs

The comparison people search for is nmslib vs faiss, and the difference in approach is real. Faiss is a similarity search library organised around indexes and quantisation for dense vectors, with a strong emphasis on compressing large collections and on GPU execution. NMSLIB is organised around spaces and methods, with the stated goal of searching generic and non-metric spaces and of serving as a toolkit for evaluating k-NN methods. If your distance is not a standard vector metric, or if your job is to compare HNSW against a VP-tree against NAPP on the same data, NMSLIB is built for that. If your job is to serve a billion dense float vectors with product quantisation, that is a different design centre.

The second comparison is nmslib hnswlib, and here the projects are related rather than competing. The README says a standalone implementation of the fastest method, HNSW, also exists as a header-only library at nmslib/hnswlib, and credits Yury Malkov, one of NMSLIB's authors, for it. So hnswlib is not an alternative in the sense of a rival; it is a narrower extraction. Choosing between them is choosing between one method and a toolbox. hnswlib gives you HNSW with no other machinery. NMSLIB gives you HNSW plus the other methods, the spaces abstraction and the Thrift server, at the cost of a larger C++ codebase to build and extend.

There is a third path worth naming for completeness: the README notes that NMSLIB became part of Amazon Elasticsearch Service. If you are already running OpenSearch or Elasticsearch, the engine may already be available to you, and the reason to link the library directly is correspondingly weaker.

## Licence and the cost of staying on NMSLIB

NMSLIB 2.x is released under the Apache License Version 2.0, and the repository carries a LICENSE-Apache-2.0 file at the top level. The README is explicit that older versions of the library included components under different licences and that this does not apply to NMSLIB 2.x. Those older components included LSHKIT under the GNU General Public License, the NN-Descent k-NN graph construction algorithm under what the README describes as a free-to-use licence similar to Apache 2, and FALCONN under MIT. If you are vendoring an old NMSLIB rather than depending on 2.x, the licence question is different and the README is the only place in the repository that summarises it. That is a factual difference between versions, not legal advice; a lawyer should read the actual files.

The upgrade cost is dominated by the release gap rather than by API churn. The last tagged release is v2.1.1 from 2021-02-03, and the README documents no migration guide between major versions. The practical consequence is that a team adopting NMSLIB today is likely tracking the default branch or pinning a wheel, and neither is the same as pinning a release. Because the core library has no third-party dependencies, the build itself is not the expensive part; the expensive part is the custom space, if you have one, and that code is written against interfaces the README does not enumerate. Budget for reading manual/ before estimating that work.

## Conclusion

Adopt NMSLIB if you need approximate k-NN over a non-metric or custom distance and want one toolkit that also lets you benchmark several methods. Do not adopt it if HNSW is the only algorithm you will ever use: hnswlib is the header-only extraction of that same method and is the smaller dependency. Before committing, verify that your distance function is expressible as one of the built-in spaces or as an extension, and check whether the Python wheel for your interpreter version exists, since the README lists binaries for Python 3.8 through 3.13 with 3.14 only on Linux.

## FAQ

### How do I install NMSLIB?

The README advertises binary wheels, so the usual route is pip install nmslib. Binaries are documented for Python 3.8 through 3.13, plus 3.14 on Linux, on Linux, macOS and Windows for both Intel and ARM CPUs.

### What is the difference between NMSLIB and hnswlib?

The README states that a standalone implementation of NMSLIB's fastest method, HNSW, also exists as the header-only hnswlib library, and credits Yury Malkov, one of NMSLIB's authors. NMSLIB additionally carries other search methods, the spaces abstraction and a Thrift query server.

### Can I use NMSLIB with a custom distance function that is not a metric?

Non-metric and generic spaces are the project's stated focus, and the README describes NMSLIB as an extendible library where new search methods and distance functions can be added. The README does not document a Python-level way to register an arbitrary distance, so a custom function implies writing C++ against the library's interfaces.

### Does NMSLIB have a Java client?

Yes. The README describes a query server usable through Apache Thrift version 0.12, with a native Java client that works on many platforms without requiring a C++ library to be installed.

### What licence is NMSLIB released under?

The code is released under the Apache License Version 2.0, and the repository contains a LICENSE-Apache-2.0 file. The README notes that older versions included components under other licences, such as LSHKIT under the GPL, but states that this does not apply to NMSLIB 2.x.

## Sources

- [Issues](https://github.com/nmslib/nmslib/issues)
- [License: Apache-2.0](https://github.com/nmslib/nmslib/blob/master/LICENSE)
- [nmslib/nmslib on GitHub](https://github.com/nmslib/nmslib)
- [README](https://github.com/nmslib/nmslib/blob/master/README.md)
- [Releases](https://github.com/nmslib/nmslib/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/nmslib-nmslib