/cuml

name: cuml
description: >-
  Use when writing, running, debugging or upgrading Python code that uses NVIDIA cuML
  (GPU machine learning), cuml.accel (zero-code-change GPU acceleration of scikit-learn,
  umap-learn and hdbscan), or GPU UMAP/HDBSCAN/RandomForest/KMeans/SVC, including through
  libraries that wrap cuML (BERTopic, rapids-singlecell). Covers APIs removed or renamed in
  2025-2026 releases, verifying code really ran on the GPU, large-data UMAP/HDBSCAN memory
  recipes, and exporting trained models. Not for cuDF-only dataframe work, PyTorch or XGBoost.

cuML

cuML releases every two months and removes deprecated APIs, so your training data is likely to contain APIs that no longer exist. Look things up in the installed cuML instead of recalling them.

Ground facts

• Install from pypi.org: `pip install cuml-cu13` (CUDA 13 driver, >= 580) or `cuml-cu12`.

No extra index URL is needed. `pip install cuml` installs an unrelated placeholder.

• Check the [installation guide](https://docs.nvidia.com/datascience/install/) for supported

GPUs, operating systems, Python versions, CUDA/driver requirements, and install commands. Linux only; on Windows use WSL2.

• Google Colab GPU runtimes ship cuML preinstalled: check `pip list` before installing anything there.
• `cuml.accel` runs unmodified scikit-learn / umap-learn / hdbscan code on the GPU and falls

back to the CPU for anything unsupported. It accelerates RandomForest, LogisticRegression, Ridge, KMeans, DBSCAN, PCA, SVC, KNN, UMAP, HDBSCAN, scalers, encoders and more.

• Enable it with `python -m cuml.accel script.py`, `%load_ext cuml.accel` (first notebook

cell), `CUML_ACCEL_ENABLED=1`, or `cuml.accel.install()` before importing sklearn.

Step 1: look it up in the installed cuML

• Check the versions and answer for them:

`python -c "import cuml, sklearn; print(cuml.__version__, sklearn.__version__)"`.

• Before using a cuML class, function or argument, confirm it exists and read its

documentation: `python -c "import inspect, cuml; print(inspect.signature(cuml.svm.SVC))"`, `help(cuml.manifold.UMAP)`. Docstrings list valid values, for example the accepted `build_kwds` keys and `output_type` values.

• Run the code and read the errors: removed arguments raise `TypeError`, removed modules

`ModuleNotFoundError`, invalid values usually list the valid ones.

• Treat deprecated APIs as removed: do not recommend anything that emits a `FutureWarning` or

is marked deprecated in its docstring, even if it still works in the installed version. Deprecation warnings only appear when the code runs, so run the code you suggest (on small data if needed) with `python -W always::FutureWarning` and read the warnings; they name the replacement.

• For `cuml.accel`, see below for how to find out what runs on the GPU.

Step 2: check code for removed APIs

Run `python scripts/check_removed_apis.py <files or dirs>` (path relative to this skill) on the user's code and on code you write, before presenting it. It reports removed APIs whose replacement the installed cuML does not reveal, with the replacement, for example `cuml.fil` (use nvForest), `SVC(probability=True)` (use `CalibratedClassifierCV`) and renamed UMAP/HDBSCAN `build_kwds` keys that are silently ignored.

The checker only knows about these few APIs. An empty result does not mean the code is current, and it says nothing about whether `cuml.accel` runs it on the GPU; still do Step 1 and check `cuml.accel` fallbacks as described below.

Behavior that changed without an API change:

• RandomForest is reproducible with `random_state` alone (since 25.10). Do not set

`n_streams=1` "for determinism"; that advice is outdated and only slows training.

• `KMeans.transform` returns Euclidean, not squared, distances (since 26.10).

cuml.accel

• Activate before sklearn is imported. In a notebook that already imported sklearn,

restart the kernel and make `%load_ext cuml.accel` the first cell.

• With cudf.pandas: `python -m cudf.pandas -m cuml.accel script.py`, or

`%load_ext cudf.pandas` then `%load_ext cuml.accel`.

• Prove where code ran instead of assuming: `python -m cuml.accel -v script.py` logs

"ran on GPU" / "falling back to CPU: <reason>"; `--profile` (or `%%cuml.accel.profile`, or `with cuml.accel.profile():`) prints a per-call GPU/CPU table. `cuml.accel.is_proxy(est)` only says the estimator is wrapped, not that it ran on the GPU.

• Unsupported parameters and inputs fall back to the CPU silently. Do not recall fallback

lists: run with `-v` or `--profile` and read the reasons, or, without running, read the documentation for the installed release from GitHub: `https://raw.githubusercontent.com/NVIDIA/cuml/v<cuml.__version__>/docs/source/cuml-accel/compatibility.rst` (for example `v26.08.00`; for 26.06 and earlier the file is `limitations.rst`; for nightly builds such as `26.12.00a5` use `main` instead of the tag).

• Single GPU only. To use several GPUs, run separate processes with `CUDA_VISIBLE_DEVICES`.
• Models trained under accel pickle as plain sklearn/umap/hdbscan objects and load without

cuML. The pickle bytes still contain the string `cuml` (a reconstructor), so do not use "no `cuml` in the bytes" as a check; load it in a CPU-only environment instead.

• Results are comparable in quality, not numerically identical, to the CPU libraries.

See `references/parity-and-numerics.md` before treating a difference as a bug.

Large data (UMAP, HDBSCAN, KMeans)

• UMAP `build_algo="auto"` already uses NN-Descent above 50,000 rows (unless `random_state`

is set, which forces brute force). HDBSCAN defaults to `build_algo="brute_force"`.

• Out of memory on the kNN build: batch it with

`build_algo="nn_descent", build_kwds={"knn_n_clusters": 4, "knn_overlap_factor": 2}` (increase `knn_n_clusters` to 8, 16, ... to use less memory). Unknown keys are ignored without a warning, so spell them exactly.

• Oversubscribe GPU memory with managed me