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 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: "; --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 memory:
import rmm; rmm.reinitialize(managed_memory=True) before creating estimators.
cuml.accel enables managed memory by default (not on WSL2).
- KMeans on host data larger than the GPU:
KMeans(device_buffer_samples=...) streams host
batches (26.08+).
- HDBSCAN soft clustering: fit with
prediction_data=True, then use
cuml.cluster.hdbscan.all_points_membership_vectors, membership_vector and
approximate_predict. There is no HDBSCAN.predict and no .prediction submodule.
Exporting models
| Have |
Want |
Use |
| cuML estimator |
scikit-learn object for a CPU-only machine |
est.as_sklearn() |
| scikit-learn estimator |
cuML estimator |
cuml.<Estimator>.from_sklearn(skl) |
| cuML RandomForest |
Treelite / fast GPU or CPU inference |
rf.as_treelite(), rf.as_nvforest() |
| sklearn / XGBoost / LightGBM forest |
fast inference |
nvforest.load_from_sklearn(model), nvforest.load_model(path) |
| accel-trained model |
ONNX |
skl2onnx on the proxy (not DBSCAN, TSNE, UMAP, HDBSCAN, NearestNeighbors) |
Outputs
Outputs mirror the input container: NumPy in, NumPy out; cuDF in, cuDF out. With cuDF or
dask_cudf input, fitted attributes such as cluster_centers_ are cuDF objects, so call
.to_pandas() / .to_numpy() before handing them to pandas or matplotlib. Force a type
with output_type="cupy" on the estimator, cuml.set_global_output_type("cupy"), or
with cuml.using_output_type("cupy"): (global and context settings take precedence).
Non-float input is converted to float32 by default.
1---2name: cuml3description: >-4 Use when writing, running, debugging or upgrading Python code that uses NVIDIA cuML5 (GPU machine learning), cuml.accel (zero-code-change GPU acceleration of scikit-learn,6 umap-learn and hdbscan), or GPU UMAP/HDBSCAN/RandomForest/KMeans/SVC, including through7 libraries that wrap cuML (BERTopic, rapids-singlecell). Covers APIs removed or renamed in8 2025-2026 releases, verifying code really ran on the GPU, large-data UMAP/HDBSCAN memory9 recipes, and exporting trained models. Not for cuDF-only dataframe work, PyTorch or XGBoost.10metadata:11 source: https://skillmd.com/skills/nvidia/cuml12---1314# cuML1516cuML releases every two months and removes deprecated APIs, so your training data is likely17to contain APIs that no longer exist. Look things up in the installed cuML instead of18recalling them.1920## Ground facts2122- Install from pypi.org: `pip install cuml-cu13` (CUDA 13 driver, >= 580) or `cuml-cu12`.23 No extra index URL is needed. `pip install cuml` installs an unrelated placeholder.24- Check the [installation guide](https://docs.nvidia.com/datascience/install/) for supported25 GPUs, operating systems, Python versions, CUDA/driver requirements, and install commands.26 Linux only; on Windows use WSL2.27- Google Colab GPU runtimes ship cuML preinstalled: check `pip list` before installing anything there.28- `cuml.accel` runs unmodified scikit-learn / umap-learn / hdbscan code on the GPU and falls29 back to the CPU for anything unsupported. It accelerates RandomForest, LogisticRegression,30 Ridge, KMeans, DBSCAN, PCA, SVC, KNN, UMAP, HDBSCAN, scalers, encoders and more.31- Enable it with `python -m cuml.accel script.py`, `%load_ext cuml.accel` (first notebook32 cell), `CUML_ACCEL_ENABLED=1`, or `cuml.accel.install()` before importing sklearn.3334## Step 1: look it up in the installed cuML3536- Check the versions and answer for them:37 `python -c "import cuml, sklearn; print(cuml.__version__, sklearn.__version__)"`.38- Before using a cuML class, function or argument, confirm it exists and read its39 documentation: `python -c "import inspect, cuml; print(inspect.signature(cuml.svm.SVC))"`,40 `help(cuml.manifold.UMAP)`. Docstrings list valid values, for example the accepted41 `build_kwds` keys and `output_type` values.42- Run the code and read the errors: removed arguments raise `TypeError`, removed modules43 `ModuleNotFoundError`, invalid values usually list the valid ones.44- Treat deprecated APIs as removed: do not recommend anything that emits a `FutureWarning` or45 is marked deprecated in its docstring, even if it still works in the installed version.46 Deprecation warnings only appear when the code runs, so run the code you suggest (on small47 data if needed) with `python -W always::FutureWarning` and read the warnings; they name the48 replacement.49- For `cuml.accel`, see below for how to find out what runs on the GPU.5051## Step 2: check code for removed APIs5253Run `python scripts/check_removed_apis.py <files or dirs>` (path relative to this skill) on54the user's code and on code you write, before presenting it. It reports removed APIs whose55replacement the installed cuML does not reveal, with the replacement, for example56`cuml.fil` (use nvForest), `SVC(probability=True)` (use `CalibratedClassifierCV`) and57renamed UMAP/HDBSCAN `build_kwds` keys that are silently ignored.5859The checker only knows about these few APIs. An empty result does not mean the code is60current, and it says nothing about whether `cuml.accel` runs it on the GPU; still do Step 161and check `cuml.accel` fallbacks as described below.6263Behavior that changed without an API change:64- RandomForest is reproducible with `random_state` alone (since 25.10). Do not set65 `n_streams=1` "for determinism"; that advice is outdated and only slows training.66- `KMeans.transform` returns Euclidean, not squared, distances (since 26.10).6768## cuml.accel6970- Activate before sklearn is imported. In a notebook that already imported sklearn,71 restart the kernel and make `%load_ext cuml.accel` the first cell.72- With cudf.pandas: `python -m cudf.pandas -m cuml.accel script.py`, or73 `%load_ext cudf.pandas` then `%load_ext cuml.accel`.74- Prove where code ran instead of assuming: `python -m cuml.accel -v script.py` logs75 "ran on GPU" / "falling back to CPU: <reason>"; `--profile` (or `%%cuml.accel.profile`,76 or `with cuml.accel.profile():`) prints a per-call GPU/CPU table.77 `cuml.accel.is_proxy(est)` only says the estimator is wrapped, not that it ran on the GPU.78- Unsupported parameters and inputs fall back to the CPU silently. Do not recall fallback79 lists: run with `-v` or `--profile` and read the reasons, or, without running, read the80 documentation for the installed release from GitHub:81 `https://raw.githubusercontent.com/NVIDIA/cuml/v<cuml.__version__>/docs/source/cuml-accel/compatibility.rst`82 (for example `v26.08.00`; for 26.06 and earlier the file is `limitations.rst`; for nightly83 builds such as `26.12.00a5` use `main` instead of the tag).84- Single GPU only. To use several GPUs, run separate processes with `CUDA_VISIBLE_DEVICES`.85- Models trained under accel pickle as plain sklearn/umap/hdbscan objects and load without86 cuML. The pickle bytes still contain the string `cuml` (a reconstructor), so do not use87 "no `cuml` in the bytes" as a check; load it in a CPU-only environment instead.88- Results are comparable in quality, not numerically identical, to the CPU libraries.89 See `references/parity-and-numerics.md` before treating a difference as a bug.9091## Large data (UMAP, HDBSCAN, KMeans)9293- UMAP `build_algo="auto"` already uses NN-Descent above 50,000 rows (unless `random_state`94 is set, which forces brute force). HDBSCAN defaults to `build_algo="brute_force"`.95- Out of memory on the kNN build: batch it with96 `build_algo="nn_descent", build_kwds={"knn_n_clusters": 4, "knn_overlap_factor": 2}`97 (increase `knn_n_clusters` to 8, 16, ... to use less memory). Unknown keys are ignored98 without a warning, so spell them exactly.99- Oversubscribe GPU memory with managed memory:100 `import rmm; rmm.reinitialize(managed_memory=True)` before creating estimators.101 `cuml.accel` enables managed memory by default (not on WSL2).102- KMeans on host data larger than the GPU: `KMeans(device_buffer_samples=...)` streams host103 batches (26.08+).104- HDBSCAN soft clustering: fit with `prediction_data=True`, then use105 `cuml.cluster.hdbscan.all_points_membership_vectors`, `membership_vector` and106 `approximate_predict`. There is no `HDBSCAN.predict` and no `.prediction` submodule.107108## Exporting models109110| Have | Want | Use |111|---|---|---|112| cuML estimator | scikit-learn object for a CPU-only machine | `est.as_sklearn()` |113| scikit-learn estimator | cuML estimator | `cuml.<Estimator>.from_sklearn(skl)` |114| cuML RandomForest | Treelite / fast GPU or CPU inference | `rf.as_treelite()`, `rf.as_nvforest()` |115| sklearn / XGBoost / LightGBM forest | fast inference | `nvforest.load_from_sklearn(model)`, `nvforest.load_model(path)` |116| accel-trained model | ONNX | `skl2onnx` on the proxy (not DBSCAN, TSNE, UMAP, HDBSCAN, NearestNeighbors) |117118## Outputs119120Outputs mirror the input container: NumPy in, NumPy out; cuDF in, cuDF out. With cuDF or121dask_cudf input, fitted attributes such as `cluster_centers_` are cuDF objects, so call122`.to_pandas()` / `.to_numpy()` before handing them to pandas or matplotlib. Force a type123with `output_type="cupy"` on the estimator, `cuml.set_global_output_type("cupy")`, or124`with cuml.using_output_type("cupy"):` (global and context settings take precedence).125Non-float input is converted to float32 by default.