Knowhere: the C++ vector search engine inside Milvus

Knowhere is a library, not a vector database

The README opens with a sentence that settles most adoption questions: Knowhere is written in C++, and it is "an independent project that act as Milvus's internal core." That is the whole scope. It is the layer Milvus calls when a query needs approximate nearest neighbour search, and it wraps several index families rather than inventing one. The repository topics list faiss, hnsw, gpu, nearest-neighbor-search, vector and vector-database, but the last of those describes the ecosystem it lives in, not what you get when you clone it.

The problem it solves is narrow and real. If you maintain a system that stores vectors and answers similarity queries, you eventually need HNSW for low latency in memory, something disk-resident for collections too large to hold in RAM, and GPU paths for bulk work. Knowhere collects those algorithms behind one build and one interface so that Milvus does not carry a separate integration for each. The audience is therefore C++ engineers working on or alongside Milvus, plus people who want the pyknowhere wheel for experiments without running the full database.

If you arrived here looking for a service to start, a port to connect to, or a query language, this is the wrong repository. There is no server binary described in the README, no storage engine and no CLI. The homepage field points at the Milvus project, which is where the database lives.

How the build and index layers fit together

The architecture visible from the repository root is a Conan plus CMake build with a Makefile facade. `conanfile.py` resolves third-party dependencies, `cmake/` holds the CMake modules, `src/` holds the engine, `include/` holds the public headers, and `thirdparty/` carries vendored code. The Makefile comment is explicit that "conan + cmake put build outputs" under BUILD_DIR, and that binaries land at `$(BUILD_DIR)/$(BUILD_TYPE)/...`, so a default release build produces `build/Release/...`.

The Makefile is also where the real design decisions surface. Build variants are opt-in variables: WITH_GPU, WITH_UT, WITH_BENCHMARK, WITH_ASAN, WITH_SVS, WITH_CARDINAL and WITH_DEBUG. One comment explains why `unexport` appears in the file: without it, GNU Make exports command-line variables such as WITH_ASAN into every sub-process, and the custom folly recipe picks up `$ENV{WITH_ASAN}` and compiles folly itself with `-fsanitize=address`, which the comment says breaks the build on GCC. That is a concrete example of the kind of friction a multi-backend C++ library accumulates.

Two other details matter for anyone reading the build. First, `export CMAKE_POLICY_VERSION_MINIMUM ?= 3.5` exists because CMake 4.x dropped compatibility with `cmake_minimum_required` versions below 3.5, and Conan-built third-party packages need to inherit the setting. Second, the compiler is selectable through a Conan profile rather than a direct compiler flag, which is why the README shows `make CONAN_PROFILE=clang14` as the example for clang or gcc-15.

Installing Knowhere and building a first release

The README gives a two-step path: install dependencies, then build. `scripts/install_deps.sh` is described as installing "all dependencies for building, testing, and shipping the knowhere library", and the README suggests reading and trimming that file if you do not need the full pipeline. This script is the part most likely to surprise you, because it decides what lands on your machine.

$ bash scripts/install_deps.sh

With dependencies in place, the default target is a CPU release build. The README presents `make` on its own as the CPU release case, and `make help` as the way to list every target and flag.

# CPU release (default)
$ make

# CPU with unit tests
$ make WITH_UT=True

A plain `make` produces the library under `build/Release/`. If you want to run the test suite, you must have built with unit tests enabled first, because the README notes that `make test` "requires a prior build with WITH_UT=True". The GPU path is a separate build using cuVS, invoked as `make WITH_GPU=True`, and it can be combined with unit tests.

# GPU release (cuVS)
$ make WITH_GPU=True

# GPU with unit tests
$ make WITH_GPU=True WITH_UT=True

For Python, the wheel is built after a Release configuration and needs swig plus Python development headers, which the dependency script installs. The README shows `make wheel` followed by a pip install of the resulting manylinux wheel from `python/dist/`, and points at `python/build_portable_wheel.sh -h` for clean, verbose and custom-Python options. The README does not document a rollback procedure for a wheel install, so plan on a virtual environment if you need to undo one.

Verified platforms, and where the build is likely to fail

The README is unusually direct about platform support: the verified list is Ubuntu 22.04 on x86_64 and Aarch64, Ubuntu 20.04 on x86_64 and Aarch64, and MacOS on both x86_64 and Apple Silicon. Ubuntu 20.04 is annotated as EOL by April 2025 and "kept for legacy reasons", with `scripts/install_deps.sh` named as the place to see the details. Other Linux distributions are described as welcome but unverified, so a build there is your problem to debug.

The limitation that matters most is not a bug, it is the boundary of the project. Knowhere has no persistence, no replication and no query planner. If your requirement is a vector database you can deploy and operate, Knowhere is the wrong tool, and the README says so indirectly by recommending that users who only want Knowhere inside Milvus "move to the Milvus main project and build Milvus directly, where Knowhere is then built implicitly during Milvus build." Building it standalone is for people changing the engine, not for people running search.

There is a second, quieter failure mode: the build surface is large. Conan resolves third-party packages, CMake policy versions have to be pinned for CMake 4.x, and optional backends such as SVS and Cardinal are gated behind their own variables. A first build on an unsupported toolchain can fail inside a dependency rather than in Knowhere's own source, which makes the error message misleading. Budget time for that, and use `make CONAN_PROFILE=` to pin a compiler you know works.

Knowhere versus using FAISS directly

The obvious alternative is FAISS itself, which appears in the repository topics and is one of the libraries Knowhere integrates. The difference in approach is packaging and scope. FAISS gives you index implementations and expects you to own the surrounding concerns: which index type to instantiate, how to serialize it, how to keep it consistent across processes. Knowhere sits one level up, as the component Milvus uses to pick and drive an index, adding HNSW and DiskANN alongside the FAISS-backed paths and exposing build-time switches for GPU and sanitizer variants.

That means Knowhere is the better choice when you want the selection logic and the multi-backend wiring already done, and FAISS is the better choice when you want a single well-known library with no Conan layer, no CMake policy pinning and no Makefile variable matrix. The trade is real in both directions: Knowhere inherits a heavier build because it carries more, and FAISS leaves integration work to you because it carries less. For a Milvus contributor the question is settled, since Knowhere is the internal core. For anyone else, the deciding factor is whether you want the engine or the plumbing around it.

A second alternative is simply running Milvus. If your goal is search over vectors and not changes to the search code, the README's own advice applies: build Milvus, and Knowhere comes along implicitly.

Maintenance, releases and the Apache-2.0 terms

The repository is not archived, and the last push was on 2026-09-14, one day before this writing. Two release lines are visible: v3.0.4 and v2.6.16, both dated 2026-06-17, with v3.0.3 on 2026-05-30. The presence of a maintained 2.6 line next to 3.0 suggests that upgrading across the major version is not treated as a drop-in move, and the README does not publish a migration guide, so pinning to a known tag is the safer default for anyone building from source.

Upgrade cost is dominated by the build, not by an API surface. A version bump can change what Conan resolves, which third-party recipes compile, and whether the CMake policy pin still applies. If you build Knowhere inside Milvus, that cost is absorbed by the Milvus build; if you build it standalone, you own it. The `make clean` target exists for the obvious reason, and `make help` is the fastest way to see what a given checkout exposes before you change anything.

Knowhere is licensed under Apache-2.0, and the Makefile carries the standard Zilliz copyright header with the licence reference. Apache-2.0 is a permissive licence with an explicit patent grant and requires that notices be preserved. What that means for your product is a question for your own legal review, not something this article can settle, and the repository's LICENSE file is the authoritative text.

Editorial conclusion

Adopt Knowhere if you are modifying Milvus's search path, writing C++ index code, or need the pyknowhere wheel for offline experiments; do not adopt it if you want a running vector database, because it has no server, no storage layer and no query language. Before building, check that your OS is on the verified list in the README, read scripts/install_deps.sh to see what it will pull in, and run make help to confirm which targets your checkout exposes.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. zilliztech/knowhere on GitHub