RAFT Python Library (CUDA 12)

Common errors

• ModuleNotFoundError: No module named 'raft'

  cause The `pylibraft-cu12` package is not installed or not available in the current Python environment.
  fix Install the package using `pip install pylibraft-cu12` (and `cupy-cuda12x` for practical use).

• RuntimeError: CUDA driver version is insufficient for CUDA runtime version

  cause Your installed NVIDIA CUDA driver is older than what `pylibraft-cu12` (which requires CUDA 12.2+) expects, or there's a mismatch between your system's CUDA Toolkit and driver.
  fix Update your NVIDIA GPU drivers to the latest version. Ensure your system's CUDA Toolkit version (if installed) is 12.2 or higher, matching the `cu12` suffix in `pylibraft-cu12`.

• AttributeError: module 'raft.neighbors' has no attribute 'OldAlgorithmName'

  cause A specific algorithm, class, or function within a RAFT module was removed or renamed in a newer version due to API restructuring (e.g., in v26.02.00 or v26.04.00).
  fix Consult the `raft` Python API documentation for your installed version or the release notes on GitHub for renamed or removed features. You may need to update your code to use an alternative or refactored API.

• TypeError: __init__() got an unexpected keyword argument 'old_parameter'

  cause The constructor or method signature of a RAFT class or function has changed, often due to a breaking change in a newer version.
  fix Review the `raft` Python API documentation for the specific class/function and your installed `pylibraft-cu12` version to identify the correct parameters and their usage. Update your code accordingly.

Warnings

• breaking As of v25.12.00, `pylibraft-cu12` (and all `raft` variants) explicitly require CUDA 12.2 or newer. Using older CUDA versions will result in runtime errors or compilation failures.
  Fix: Ensure your system has CUDA Toolkit 12.2+ installed and configured correctly. For Docker, use RAPIDS base images built for CUDA 12.2+.
• breaking In v26.02.00, significant internal C++ API restructuring occurred, including the removal of certain specific `neighbors/`, `cluster/`, `distance/`, `spatial/`, and `sparse/neighbors/` APIs. While core Python modules like `raft.neighbors` persist, specific less common algorithms, classes, or parameters within these modules may have been removed or changed.
  Fix: Consult the RAFT Python documentation for your specific version (e.g., `docs.rapids.ai/api/raft/stable/api_docs/python/`). Adapt your code to use available functions/parameters or alternative algorithms.
• breaking The `lanczos` solver API was renamed in v26.04.00. If you were using this specific linear algebra component, your code will break.
  Fix: Update your code to use the new name for the Lanczos solver. Refer to the RAFT release notes or API documentation for the correct symbol name.
• gotcha Installing `pylibraft-cu12` only provides the RAFT bindings. You will almost certainly need `cupy-cuda12x` (or another GPU array library like `cudf` for dataframes) to effectively work with GPU arrays required by RAFT algorithms.
  Fix: Always install `cupy-cuda12x` alongside `pylibraft-cu12` for practical use cases: `pip install pylibraft-cu12 cupy-cuda12x`.
• gotcha RAPIDS libraries, including RAFT, follow a monthly release cycle. This means breaking changes can occur frequently between minor version updates, requiring regular attention to release notes when upgrading.
  Fix: Pin your `pylibraft-cu12` version in `requirements.txt` to avoid unexpected breakage on update (e.g., `pylibraft-cu12==26.4.0`), and review release notes (e.g., on `github.com/rapidsai/raft/releases`) before upgrading.

Install

• pip install pylibraft-cu12 cupy-cuda12x Recommended installation with CuPy
• pip install pylibraft-cu12 Minimal installation (requires separate CuPy/GPU array handling)

Imports

• NearestNeighbors

  from raft.neighbors import NearestNeighbors

• KMeans

  from raft.cluster import KMeans

• get_device_info
  wrong:

  from pylibraft.common.cuda_utils import get_device_info

  correct:

  from raft.common.cuda_utils import get_device_info

  The installed package is `pylibraft-cu12`, but the import namespace for Python bindings is `raft`.
• LinearRegression

  from raft.linear_model import LinearRegression

Quickstart

This quickstart demonstrates how to use `raft.neighbors.NearestNeighbors` to find the k-nearest neighbors on GPU data using CuPy. It initializes random GPU data, fits a NearestNeighbors model, and queries for neighbors. Ensure you have `cupy-cuda12x` installed for this example to run and a CUDA-enabled GPU.

import cupy as cp
from raft.neighbors import NearestNeighbors
import sys

# Ensure CuPy is installed for GPU array handling and a CUDA device is available
try:
    if cp.cuda.runtime.getDeviceCount() == 0:
        print("Error: No CUDA device found. RAFT requires a CUDA-enabled GPU.")
        sys.exit(1)
except cp.cuda.runtime.CUDARuntimeError as e:
    print(f"Error initializing CuPy or CUDA runtime: {e}")
    print("Please ensure CuPy is installed correctly (e.g., `cupy-cuda12x`) and your CUDA environment is set up.")
    sys.exit(1)

# Generate some random GPU data using CuPy
n_samples = 100
n_features = 10
X = cp.random.rand(n_samples, n_features, dtype=cp.float32)

# Create a NearestNeighbors model
nn = NearestNeighbors(n_neighbors=5, metric='euclidean', output_type='cupy')

# Fit the model to the data
nn.fit(X)

# Query for nearest neighbors to the same data
distances, indices = nn.kneighbors(X)

print("Distances shape:", distances.shape)
print("Indices shape:", indices.shape)
print("\nFirst 5 distances (sample 0):\n", distances[0, :5])
print("\nFirst 5 indices (sample 0):\n", indices[0, :5])