{"id":9220,"library":"pylibraft-cu12","title":"RAFT Python Library (CUDA 12)","description":"pylibraft-cu12 is the Python binding for RAFT (Reusable Algorithms Functions and other Tools), a core component of the NVIDIA RAPIDS ecosystem providing a collection of GPU-accelerated primitives and algorithms for data science. It is designed for optimal performance on NVIDIA GPUs with CUDA 12.x. The current version is 26.4.0, following a monthly release cadence aligned with the broader RAPIDS project.","status":"active","version":"26.4.0","language":"en","source_language":"en","source_url":"https://github.com/rapidsai/raft","tags":["rapids","gpu","cuda","machine-learning","data-science","numerical-computing","high-performance"],"install":[{"cmd":"pip install pylibraft-cu12 cupy-cuda12x","lang":"bash","label":"Recommended installation with CuPy"},{"cmd":"pip install pylibraft-cu12","lang":"bash","label":"Minimal installation (requires separate CuPy/GPU array handling)"}],"dependencies":[{"reason":"Essential for handling GPU arrays (like CuPy arrays) that RAFT algorithms operate on. While not a direct dependency, RAFT is mostly unusable without it.","package":"cupy-cuda12x","optional":true}],"imports":[{"symbol":"NearestNeighbors","correct":"from raft.neighbors import NearestNeighbors"},{"symbol":"KMeans","correct":"from raft.cluster import KMeans"},{"note":"The installed package is `pylibraft-cu12`, but the import namespace for Python bindings is `raft`.","wrong":"from pylibraft.common.cuda_utils import get_device_info","symbol":"get_device_info","correct":"from raft.common.cuda_utils import get_device_info"},{"symbol":"LinearRegression","correct":"from raft.linear_model import LinearRegression"}],"quickstart":{"code":"import cupy as cp\nfrom raft.neighbors import NearestNeighbors\nimport sys\n\n# Ensure CuPy is installed for GPU array handling and a CUDA device is available\ntry:\n    if cp.cuda.runtime.getDeviceCount() == 0:\n        print(\"Error: No CUDA device found. RAFT requires a CUDA-enabled GPU.\")\n        sys.exit(1)\nexcept cp.cuda.runtime.CUDARuntimeError as e:\n    print(f\"Error initializing CuPy or CUDA runtime: {e}\")\n    print(\"Please ensure CuPy is installed correctly (e.g., `cupy-cuda12x`) and your CUDA environment is set up.\")\n    sys.exit(1)\n\n# Generate some random GPU data using CuPy\nn_samples = 100\nn_features = 10\nX = cp.random.rand(n_samples, n_features, dtype=cp.float32)\n\n# Create a NearestNeighbors model\nnn = NearestNeighbors(n_neighbors=5, metric='euclidean', output_type='cupy')\n\n# Fit the model to the data\nnn.fit(X)\n\n# Query for nearest neighbors to the same data\ndistances, indices = nn.kneighbors(X)\n\nprint(\"Distances shape:\", distances.shape)\nprint(\"Indices shape:\", indices.shape)\nprint(\"\\nFirst 5 distances (sample 0):\\n\", distances[0, :5])\nprint(\"\\nFirst 5 indices (sample 0):\\n\", indices[0, :5])","lang":"python","description":"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."},"warnings":[{"fix":"Ensure your system has CUDA Toolkit 12.2+ installed and configured correctly. For Docker, use RAPIDS base images built for CUDA 12.2+.","message":"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.","severity":"breaking","affected_versions":">=25.12.00"},{"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.","message":"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.","severity":"breaking","affected_versions":">=26.02.00"},{"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.","message":"The `lanczos` solver API was renamed in v26.04.00. If you were using this specific linear algebra component, your code will break.","severity":"breaking","affected_versions":">=26.04.00"},{"fix":"Always install `cupy-cuda12x` alongside `pylibraft-cu12` for practical use cases: `pip install pylibraft-cu12 cupy-cuda12x`.","message":"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.","severity":"gotcha","affected_versions":"all"},{"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.","message":"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.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install the package using `pip install pylibraft-cu12` (and `cupy-cuda12x` for practical use).","cause":"The `pylibraft-cu12` package is not installed or not available in the current Python environment.","error":"ModuleNotFoundError: No module named 'raft'"},{"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`.","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.","error":"RuntimeError: CUDA driver version is insufficient for CUDA runtime version"},{"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.","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).","error":"AttributeError: module 'raft.neighbors' has no attribute 'OldAlgorithmName'"},{"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.","cause":"The constructor or method signature of a RAFT class or function has changed, often due to a breaking change in a newer version.","error":"TypeError: __init__() got an unexpected keyword argument 'old_parameter'"}]}