{"id":9078,"library":"libraft-cu12","title":"RAFT (libraft-cu12)","description":"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.","status":"active","version":"26.4.0","language":"en","source_language":"en","source_url":"https://github.com/rapidsai/raft","tags":["GPU","CUDA","RAPIDS","Machine Learning","Data Science","High Performance Computing","C++"],"install":[{"cmd":"pip install libraft-cu12 --extra-index-url https://pypi.nvidia.com","lang":"bash","label":"Install with pip (requires NVIDIA PyPI index)"},{"cmd":"mamba install -c rapidsai -c conda-forge libraft-cu12 cuda-version=12.x","lang":"bash","label":"Install with mamba (Conda, recommended)"}],"dependencies":[{"reason":"RAFT is a CUDA-accelerated library; requires CUDA Toolkit 12.2+ for recent versions.","package":"CUDA Toolkit","optional":false},{"reason":"For Python users, 'pylibraft' provides Python bindings and is the typical interface to RAFT functionalities, depending on 'libraft-cu12' for the core C++ library.","package":"pylibraft","optional":true},{"reason":"Often used with pylibraft for GPU array interoperability, but not a hard dependency.","package":"cupy","optional":true}],"imports":[{"note":"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.","wrong":"from libraft_cu12 import SomeClass","symbol":"No direct Python API","correct":"import pylibraft"}],"quickstart":{"code":"# libraft-cu12 provides the C++ core for RAFT.\n# Python users typically interact with RAFT functionality via the `pylibraft` package.\n# Ensure pylibraft-cu12 is installed (it depends on libraft-cu12):\n# pip install pylibraft-cu12 --extra-index-url https://pypi.nvidia.com\n\nimport cupy as cp\nfrom pylibraft.neighbors import ivf_pq\n\n# Example using pylibraft, which relies on libraft-cu12\nn_samples = 5000\nn_features = 50\n\n# Generate some random data on GPU using CuPy\ndataset = cp.random.random_sample((n_samples, n_features), dtype=cp.float32)\nqueries = cp.random.random_sample((100, n_features), dtype=cp.float32)\n\n# Build an IVF-PQ index\nindex_params = ivf_pq.IndexParams(\n    n_lists=1024,\n    metric=\"sqeuclidean\",\n    pq_dim=10\n)\nindex = ivf_pq.build(index_params, dataset)\n\n# Search the index\nk = 5\nsearch_params = ivf_pq.SearchParams(n_probes=20)\ndistances, neighbors = ivf_pq.search(search_params, index, queries, k)\n\nprint(f\"Distances shape: {distances.shape}\")\nprint(f\"Neighbors shape: {neighbors.shape}\")\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=25.12.00"},{"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).","message":"In v26.02.00, several major API modules for `neighbors/`, `cluster/`, `distance/`, `spatial/`, and `sparse/neighbors/` were removed.","severity":"breaking","affected_versions":">=26.02.00"},{"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`.","message":"`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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Update C++ code that uses `lanczos` or any removed headers to reflect the new naming and header structure.","message":"As of v26.04.00, the `lanczos` functionality was renamed, and several deprecated C++ headers were removed.","severity":"breaking","affected_versions":">=26.04.00"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","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.","error":"ERROR: Could not find a version that satisfies the requirement libraft-cu12 (from versions: none)"},{"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.","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.","error":"terminate called after throwing an instance of 'raft::cuda_error' what(): CUDA error encountered at: ... Reason=cudaErrorIllegalAddress: an illegal memory access was encountered"},{"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`).","cause":"`libraft-cu12` is primarily a C++ library and does not expose direct Python modules for import. Python access to RAFT is via `pylibraft`.","error":"ModuleNotFoundError: No module named 'libraft_cu12'"}]}