Install & Compatibility
Where this runs
tested against v26.2.0 · 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
✓ 59.2s
py 3.11
✕ build_error
✓ 57.8s
py 3.12
✕ build_error
✓ 44.8s
py 3.13
✕ build_error
✓ 44.4s
py 3.9
✕ build_error
✕ build_error
3430MB installed
● package 3430MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
cuvs
✓ import cuvs
✗ import libcuvs_cu12
libcuvs-cu12 is a C++ backend; the Python API is in the `cuvs` package.
CagraIndex
✓ from cuvs.neighbors import cagra
✗ from libcuvs_cu12 import CagraIndex
CAGRA index is accessed via the `cuvs` Python package.
Build a CAGRA index and search using the `cuvs` Python package. libcuvs-cu12 is the C++ backend installed automatically.
import cupy as cp
import cuvs
from cuvs.neighbors import cagra
rs = cuvs.raft.RaftResourceManager()
data = cp.random.random((1000, 128))
index = cagra.build(rs, data)
queries = cp.random.random((10, 128))
distances, neighbors = cagra.search(index, queries, k=10)
Debug
Known issues
breakingHNSW GPU hierarchy is now default as of v26.04.00. Existing HNSW parameters may need adjustment.fixReview HNSW build parameters; refer to migration guide.
affects: >=26.4.0
breakingStatic linking of libcudart is now default (v26.04.00). May conflict with existing CUDA runtime libraries.fixSet CUDA dynamic linking if needed; see RAPIDS docs.
affects: >=26.4.0
breakingCAGRA C API enums changed to stable values (v25.12.00). Old enum values no longer work.fixUpdate enum usage to match new C API header.
affects: >=25.12.0,<26.0.0
deprecatedJava bindings: `destroyIndex()` replaced by `close()` (v25.10.00).fixUse `close()` method instead of `destroyIndex()`.
affects: >=25.10.0
gotchalibcuvs-cu12 is a C++ library; do not import directly in Python. Instead, use the `cuvs` Python package.fixInstall `cuvs` (pip install cuvs) which depends on libcuvs-cu12.
affects: all
Upgrade
Version history
26.6.0latest on PyPI · released Jun 9, 2026
Audit
Dependencies
cupy-cuda12xrequiredRequired for GPU operations and data transfer
nvidia-cuda-runtime-cu12requiredCUDA runtime shared library