# Getting Started with cuml.accel

`cuml.accel` intercepts supported scikit-learn, UMAP, and HDBSCAN estimator
operations and dispatches them to GPU implementations. When an operation
cannot run on the GPU, it transparently uses the original CPU implementation
instead. A fallback may depend on the estimator, method, parameter values,
input data, or installed library version. See [Accelerated Estimator Support](../compatibility/index.html.md)
for the accelerated estimator inventory and exact fallback conditions.

CPU fallback preserves compatibility, but frequent transitions between CPU
and GPU execution may reduce the overall speedup. The
[logging and profiling tools](../logging-and-profiling/index.html.md) show which operations
ran on the GPU, which fell back to the CPU, and why.

<a id="activation-methods"></a>

## Activation Methods

Enable `cuml.accel` before importing scikit-learn, UMAP, or HDBSCAN. When
running a script, use the `cuml.accel` command-line interface:

```console
python -m cuml.accel script.py
```

In Jupyter or IPython, load the extension before other imports:

```ipython
%load_ext cuml.accel
```

In JupyterLab, you can instead enable `cuml.accel` from the GPU accelerator
toggle without loading the extension or changing the notebook. See
[Enable from the JupyterLab toolbar](../index.html.md#cuml-accel-jupyterlab-toggle) for
requirements and steps.

<a id="cuml-accel-env-var"></a>

For third-party applications whose code you do not control, set
`CUML_ACCEL_ENABLED` to `1` or `true` (case insensitive):

```console
CUML_ACCEL_ENABLED=1 python script.py
```

This loads the accelerator for every Python program launched with the variable
set and may add startup overhead. If cuML is not installed correctly, the
environment variable is silently ignored and execution remains on the CPU, so
the CLI or notebook extension is usually easier to validate. See
[Accelerating Third-Party Applications](../examples/third-party-apps/index.html.md) for more.

You can also install the accelerator programmatically before importing the
libraries it will accelerate:

```python
import cuml

cuml.accel.install()
```

<a id="what-results-to-expect"></a>

For result-equivalence and performance guidance, see
[General Behavior](../compatibility/index.html.md#general-behavior).

## Memory Management

When the platform supports it and RMM has not already been configured,
`cuml.accel` enables [managed memory](https://developer.nvidia.com/blog/unified-memory-cuda-beginners/). Managed memory can use host memory in
addition to GPU memory and migrates data as needed, reducing the risk of GPU
out-of-memory errors. It does not prevent exhaustion of combined host and
device memory, and heavy oversubscription can slow execution. Managed memory
is not enabled on WSL 2 or when RMM was configured before `cuml.accel`.
If managed-memory oversubscription causes unexpectedly slow execution, use the
CLI’s `--disable-uvm` flag to disable it and compare performance.

For workloads that always run on NVIDIA GPUs, using cuML directly may provide
more control over GPU-specific parameters and device-memory usage. Direct cuML
can also expose functionality beyond the compatible APIs provided through
`cuml.accel`. Start with `cuml.accel` when retaining an existing codebase
matters; consider direct cuML when GPU-specific tuning and control are more
important.