Install and manage cuda.ml

Install a prebuilt backend

Choose the backend for the work that environment will perform:

Install the R package, then prepare the complete backend:

install.packages("cuda.ml")
library(cuda.ml)
cuda_ml_install()

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

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 for a first model or nvForest inference and deployment 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.

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:

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:

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:

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

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:

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:

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:

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:

# 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.

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")

Troubleshooting