RAFT (libraft-cu12)

26.4.0 · active · verified Thu Apr 16

libraft-cu12 is a core C++ library providing Reusable Algorithms Functions and other Tools (RAFT) for high-performance computing on NVIDIA GPUs. It serves as a foundational component for other RAPIDS libraries, including Python wrappers like `pylibraft`. The current version is 26.4.0, and it follows a monthly release cadence, aligned with the broader RAPIDS ecosystem.

Common errors

```
ERROR: Could not find a version that satisfies the requirement libraft-cu12 (from versions: none)
```
cause The `libraft-cu12` package (and other `rapidsai` packages) are hosted on NVIDIA's PyPI index, which is not included in the default pip search paths.

fix Install using `--extra-index-url https://pypi.nvidia.com`: `pip install libraft-cu12 --extra-index-url https://pypi.nvidia.com`. Alternatively, use `conda` or `mamba` with the `rapidsai` channel.
```
terminate called after throwing an instance of 'raft::cuda_error' what(): CUDA error encountered at: ... Reason=cudaErrorIllegalAddress: an illegal memory access was encountered
```
cause This error typically indicates an issue with GPU memory access, an incompatibility between the installed CUDA Toolkit, NVIDIA driver, and the `libraft-cu12` version, or a bug in the application using RAFT.

fix Verify that your CUDA Toolkit version, NVIDIA driver, and `libraft-cu12` (and `pylibraft-cu12` if used) versions are compatible as per RAPIDS release notes. Ensure sufficient GPU memory is available. Check for recent bug fixes in newer RAFT versions.
```
ModuleNotFoundError: No module named 'libraft_cu12'
```
cause `libraft-cu12` is primarily a C++ library and does not expose direct Python modules for import. Python access to RAFT is via `pylibraft`.

fix If you intend to use RAFT from Python, install `pylibraft-cu12` (e.g., `pip install pylibraft-cu12 --extra-index-url https://pypi.nvidia.com`) and import from `pylibraft` (e.g., `import pylibraft`).

Warnings

breaking Starting with RAFT v25.12.00, CUDA Toolkit 12.2 or higher is required. Older CUDA versions (e.g., CUDA 11) are no longer supported.
Fix: Upgrade your CUDA Toolkit installation to version 12.2+ and ensure your NVIDIA driver supports it. Use `conda` or `mamba` to install `libraft-cu12` with the appropriate `cuda-version` specifier.
breaking In v26.02.00, several major API modules for `neighbors/`, `cluster/`, `distance/`, `spatial/`, and `sparse/neighbors/` were removed.
Fix: Review your code for usage of these deprecated APIs. Migrate to newer or alternative functionalities available in `pylibraft` or other RAPIDS libraries (e.g., `cuvs` for distance calculations).
gotcha `libraft-cu12` is primarily a C++ library providing low-level CUDA-accelerated primitives. While installable via pip, it does not expose direct Python imports. Python users should install and use `pylibraft-cu12` (or `pylibraft` in conda) to access RAFT's functionalities.
Fix: If you intend to use RAFT from Python, ensure you install `pylibraft-cu12` (e.g., `pip install pylibraft-cu12 --extra-index-url https://pypi.nvidia.com`) and import from `pylibraft`.
breaking As of v26.04.00, the `lanczos` functionality was renamed, and several deprecated C++ headers were removed.
Fix: Update C++ code that uses `lanczos` or any removed headers to reflect the new naming and header structure.

Install

pip install libraft-cu12 --extra-index-url https://pypi.nvidia.com Install with pip (requires NVIDIA PyPI index)
mamba install -c rapidsai -c conda-forge libraft-cu12 cuda-version=12.x Install with mamba (Conda, recommended)

Imports

No direct Python API
wrong:
```
from libraft_cu12 import SomeClass
```
correct:
```
import pylibraft
```
libraft-cu12 provides the C++ core for RAFT. Python users typically interact with RAFT functionality via the `pylibraft` package, which depends on `libraft-cu12` for the CUDA 12 toolkit. There are no direct Python symbols exposed by `libraft-cu12` itself.

Quickstart

This quickstart demonstrates usage of `pylibraft`, which is the Python interface to RAFT algorithms. `libraft-cu12` provides the underlying C++ and CUDA implementations that `pylibraft` utilizes. This example builds and queries an approximate nearest neighbor (IVF-PQ) index on GPU data using CuPy arrays.

# libraft-cu12 provides the C++ core for RAFT.
# Python users typically interact with RAFT functionality via the `pylibraft` package.
# Ensure pylibraft-cu12 is installed (it depends on libraft-cu12):
# pip install pylibraft-cu12 --extra-index-url https://pypi.nvidia.com

import cupy as cp
from pylibraft.neighbors import ivf_pq

# Example using pylibraft, which relies on libraft-cu12
n_samples = 5000
n_features = 50

# Generate some random data on GPU using CuPy
dataset = cp.random.random_sample((n_samples, n_features), dtype=cp.float32)
queries = cp.random.random_sample((100, n_features), dtype=cp.float32)

# Build an IVF-PQ index
index_params = ivf_pq.IndexParams(
    n_lists=1024,
    metric="sqeuclidean",
    pq_dim=10
)
index = ivf_pq.build(index_params, dataset)

# Search the index
k = 5
search_params = ivf_pq.SearchParams(n_probes=20)
distances, neighbors = ivf_pq.search(search_params, index, queries, k)

print(f"Distances shape: {distances.shape}")
print(f"Neighbors shape: {neighbors.shape}")

view raw JSON →