---
title: "Install and manage cuda.ml"
description: >
  Install a prebuilt or source-built backend, inspect and audit its cache, and
  prepare GPU or CPU-only deployments.
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Install and manage cuda.ml}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  eval = FALSE
)
```

The cuda.ml R package contains no compiled code. Prepare one of its pinned
native backends when setting up each environment.

## Install a prebuilt backend

Choose the backend for the work that environment will perform:

| Workload | Installation | Contents |
|---|---|---|
| cuML training or GPU inference | `cuda_ml_install()` | Complete CUDA, RAPIDS cuML, and nvForest runtime, currently about 1.6 GiB |
| nvForest CPU inference only | `cuda_ml_install(device = "cpu")` | Separate CUDA-free backend, roughly 1 MiB to download and 3 MiB installed |

Install the R package, then prepare the complete backend:

```{r install-gpu}
install.packages("cuda.ml")
library(cuda.ml)
cuda_ml_install()
```

On a CPU-only nvForest deployment host, use the smaller backend instead:

```{r install-cpu}
library(cuda.ml)
cuda_ml_install(device = "cpu")
```

The installer selects the backend for the current R minor version, verifies its
files, and caches the result. Repeating a call with the same inputs reuses that
cache. Preparing either backend does not require a GPU or load native code.

The CPU-only backend can load, restore, and run nvForest models, including
random forests trained by `cuda_ml_rand_forest()`. It cannot train cuML models
or run GPU inference. The complete backend can also run nvForest inference on a
CPU. CPU-only installation is prebuilt; its `source`, `dependencies`, and
`architectures` arguments are not supported.

Continue with [Getting started with cuda.ml](cuda-ml.html) for a first model or
[nvForest inference and deployment](nvforest.html) for CPU deployment.

## Supported systems

The native backends require Linux x86_64 with glibc 2.28 or newer. This covers
current Ubuntu, Debian, and RHEL-compatible distributions that meet the glibc
requirement. macOS, Linux ARM64, musl-based Linux, and systems with an older
glibc are not supported.

GPU-backed operations require NVIDIA driver 580 or newer and a supported GPU.
The prebuilt backend contains real targets for compute capabilities 7.5, 8.0,
8.6, 8.9, 9.0, 10.0, and 12.0, plus a compute capability 12.0 PTX image for
forward compatibility. CPU-only nvForest inference has the same operating-
system requirement but requires neither an NVIDIA GPU nor an NVIDIA driver.

### Windows through WSL2

On Windows, install a compatible Linux distribution under WSL2, then install
and run R and cuda.ml inside that distribution. The same installation commands
shown above apply there. Native Windows R cannot load the Linux cuda.ml
backend. See the RAPIDS
[WSL2 installation guide](https://docs.rapids.ai/install/#windows-wsl2) for
current Windows, WSL, and NVIDIA driver setup requirements.

## Place or mirror the cache

The default cache is `tools::R_user_dir("cuda.ml", "cache")`. Set
`CUDA_ML_CACHE_DIR` before installation to put managed files elsewhere:

```{r custom-cache}
Sys.setenv(CUDA_ML_CACHE_DIR = "/opt/cuda-ml-cache")
cuda_ml_install()
```

Set `CUDA_ML_BACKEND_MIRROR` to an `https://` or `file://` directory that
contains the exact locked backend archive:

```{r backend-mirror}
Sys.setenv(
  CUDA_ML_BACKEND_MIRROR = "file:///srv/cuda-ml-backends"
)
cuda_ml_install()
```

The installer appends the locked archive filename and keeps hash verification
enabled. The mirror setting covers the cuda.ml archive, not the complete
backend's CUDA and RAPIDS artifacts, which continue to use their pinned upstream
URLs.

GitHub tags named `cuda-ml-backend-*` identify binary-backend revisions, not R
package releases, so their number can differ from `packageVersion("cuda.ml")`.
`cuda_ml_install()` uses the backend pinned by the installed package.

## Inspect, audit, or remove a backend

These two checks have different purposes:

| Function | Use |
|---|---|
| `cuda_ml_backend_info()` | Read metadata and fast cache status without loading native code |
| `cuda_ml_runtime_audit()` | Recompute content hashes and validate native registration |

Inspect both complete and CPU-only backend status with one metadata call:

```{r backend-info}
info <- cuda_ml_backend_info()

info[c(
  "backend",
  "build_mode",
  "runtime_installed",
  "runtime_path",
  "backend_loaded"
)]

info[c(
  "nvforest_cpu_runtime_installed",
  "nvforest_cpu_runtime_path",
  "nvforest_cpu_backend_loaded"
)]
```

The result also contains the locked library versions and supported
architectures. It describes the cache, not whether a GPU can execute a model.

Run the full audit for the backend that needs validation:

```{r audit}
cuda_ml_runtime_audit()

# After cuda_ml_install(device = "cpu"):
cuda_ml_runtime_audit(device = "cpu")
```

The complete downloaded-backend audit also validates its runtime dependency
closure. The default follows the selected prebuilt or source-built complete
backend.

To remove all backend cache generations and the selected-backend record, start a
fresh R session and run:

```{r clean-cache}
library(cuda.ml)
cuda_ml_cache_clean()
```

Prepare the required backend again after cleaning.

## Build the complete backend from source

Source installation builds the complete GPU-capable backend, not the CPU-only
backend. The managed path downloads and verifies the pinned CUDA 13.2.2 and
RAPIDS 26.06 development artifacts, CMake, and Ninja, then builds Treelite 4.7.0
statically:

```{r source-managed}
cuda_ml_install(source = TRUE)
```

This path requires GNU C++ 14 or newer. It does not require Python, Conda,
Docker, a system CUDA Toolkit, a system RAPIDS installation, or a GPU. Set
`CUDA_ML_CXX` to select a compiler; otherwise cuda.ml tries `g++-14` and then
`g++`.

By default, the build compiles real targets for the distinct CUDA-visible
compute capabilities reported by `nvidia-smi`. It honors
`CUDA_VISIBLE_DEVICES` and uses the portable architecture list when detection
is unavailable. Override that policy when needed:

```{r source-architectures}
# Require successful detection from a CUDA-visible GPU.
cuda_ml_install(source = TRUE, architectures = "native")

# Build the package's relocatable architecture set.
cuda_ml_install(source = TRUE, architectures = "portable")

# Build explicit CMake CUDA targets.
cuda_ml_install(
  source = TRUE,
  architectures = "86-real;89-real"
)
```

A native-target build usually takes less time and space, but the result supports
only those architectures. Restart R before changing backend selection or source
inputs after native code has been loaded.

### Use host dependencies

The host path makes no downloads and requires every build input explicitly:

```{r source-host}
Sys.setenv(
  CUDA_HOME = "/usr/local/cuda-13.2",
  CUML_PREFIX = "/opt/rapids-26.06",
  CUML_CUDA_ARCHITECTURES = "86-real",
  CUDA_ML_CXX = "/usr/bin/g++-14"
)

cuda_ml_install(source = TRUE, dependencies = "host")
```

This path requires CUDA Toolkit 13.2.2 in `CUDA_HOME`; cuML and nvForest 26.06,
Treelite 4.7.0 headers, and `lib/libtreelite_static.a` in `CUML_PREFIX`; GNU C++
14 or newer; and CMake 3.21.1 or newer. The CUDA and RAPIDS prefixes must remain
available because the backend links to their shared libraries. Treelite is
linked statically.

## Troubleshooting

| Symptom | Action |
|---|---|
| A model operation reports that its backend is missing. | Run the installation call named in the error. |
| An audit reports failed content validation. | In a fresh R session, clean the cache and reinstall the required backend. |
| Cleaning or changing backend selection requests a restart. | Restart R so no backend is loaded, then repeat the operation. |
| `architectures = "native"` cannot detect a GPU. | Expose a GPU and `nvidia-smi`, use `"portable"`, or supply explicit targets such as `"86-real"`. |
