Skip to contents

Set up CUDA for cudaverse

Source: vignettes/gpu-setup.Rmd
gpu-setup.Rmd

Follow this guide once on the Windows or Linux computer that will run cudaverse. At the end, a short R example verifies the complete setup.

Platform support

Platform CUDA with cudaverse Required runtime
Windows 10/11 or Windows Server Supported NVIDIA driver, CUDA Driver API, cuBLAS 12, cuSOLVER 11
Supported Linux distribution Supported NVIDIA driver, libcuda, cuBLAS 12, cuSOLVER 11
macOS Not supported by current NVIDIA CUDA Use a Windows or Linux machine for CUDA work

NVIDIA changes its supported operating-system and driver matrix over time. Use the current official Windows CUDA guide or Linux CUDA guide rather than copying an old installation command.

1. Install and verify the NVIDIA driver

Install a current driver for the CUDA-capable NVIDIA GPU. Open PowerShell, Command Prompt, or a Linux shell and run:

nvidia-smi

Do not continue until this command lists the GPU without a driver error. The CUDA version shown by nvidia-smi describes driver compatibility; it does not prove that cuBLAS and cuSOLVER are installed.

2. Install CUDA 12.x

cudaverse is lightweight because it uses the CUDA installation already on your computer. It needs these NVIDIA components:

  • the CUDA Driver API from the NVIDIA driver;
  • cuBLAS major version 12; and
  • cuSOLVER major version 11.

Installing a compatible CUDA 12.x distribution from NVIDIA is the simplest way to obtain them. Use NVIDIA’s default installation choices unless your system administrator manages CUDA centrally.

Windows

Confirm that the CUDA bin directory contains:

cublas64_12.dll
cusolver64_11.dll

The NVIDIA installer normally adds its bin directory to PATH. Absolute paths select the primary DLLs, but the runtime directory also needs to be on PATH so Windows can load their dependent DLLs. If R cannot find the libraries, use these session-local settings before loading cudaverse or making the first CUDA call:

cuda_bin <- "C:/Program Files/NVIDIA GPU Computing Toolkit/CUDA/v12.x/bin"
Sys.setenv(
  PATH = paste(cuda_bin, Sys.getenv("PATH"), sep = .Platform$path.sep),
  CUDAVERSE_CUBLAS_PATH = file.path(cuda_bin, "cublas64_12.dll"),
  CUDAVERSE_CUSOLVER_PATH = file.path(cuda_bin, "cusolver64_11.dll")
)

Set cuda_bin to your existing compatible CUDA runtime directory, replacing v12.x with the installed version. Use forward slashes or escaped backslashes in R paths. This prepends the directory for the current R session only.

Linux

Ask the dynamic loader whether the libraries are visible:

ldconfig -p | grep -E 'libcuda.so|libcublas.so.12|libcusolver.so.11'

If they are installed outside the loader’s configured paths, either configure the system loader according to the NVIDIA guide or set absolute paths before loading cudaverse:

Sys.setenv(
  CUDAVERSE_CUBLAS_PATH = "/absolute/path/to/libcublas.so.12",
  CUDAVERSE_CUSOLVER_PATH = "/absolute/path/to/libcusolver.so.11"
)

Avoid pointing at an unversioned symlink from an incompatible CUDA release. The runtime self-test, not the directory name, is the final compatibility check.

macOS

CUDA 10.2 was NVIDIA’s final CUDA release for macOS. Current cudaverse native CUDA targets Windows and Linux and reports CUDA as unavailable on macOS. Use a Windows/Linux workstation, server, or cloud instance with an NVIDIA GPU for the workflows in these guides.

3. Install cudaverse

The installed R package remains small because it does not download LibTorch or copy NVIDIA runtime libraries into the package library.

4. Check that cudaverse can use CUDA

Run diagnostics in a fresh R session after changing a driver, PATH, loader configuration, or either cudaverse library-path variable:

check <- cuda_diagnostics()
check$summary
check$next_steps

The summary checks the GPU, driver, CUDA libraries, and a small calculation. If anything is missing, next_steps tells you what to fix.

5. Run a strict CUDA smoke test

This test requires CUDA and does not silently change devices:

cuda_select_device("cuda")

set.seed(1)
x_gpu <- cuda_tensor(
  matrix(rnorm(1024^2), nrow = 1024),
  device = "cuda",
  dtype = "float32"
)
y_gpu <- tensor_matmul(x_gpu, x_gpu)

tensor_device(y_gpu)
cuda_provenance(y_gpu)
cuda_memory_info("cuda")

For a successful lightweight run, provenance reports device = "cuda" and backend = "native" for the matrix multiplication.

Common problems

nvidia-smi fails

Repair or update the NVIDIA driver first. cudaverse cannot load the CUDA Driver API when the operating system cannot communicate with the GPU.

cublas_loaded or cusolver_loaded is false

Install the compatible CUDA 12.x runtime libraries or set the two absolute library paths before loading cudaverse. On Windows, also add the directory containing their dependent DLLs to PATH; the absolute-path overrides do not add it. Restart R and apply the settings before the first CUDA call.

CUDA is found, but the test calculation fails

Read check$next_steps. Restart R after changing the driver or CUDA installation, then run the diagnostic check again.

CUDA runs out of memory

  • Reduce batch_size for cuda_distance() or cuda_knn().
  • Prefer cuda_knn() over a complete pairwise distance matrix when only neighbours are needed.
  • Remove unused GPU objects and run gc() before measuring a suspected leak.
  • Inspect cuda_memory_info("cuda"); whole-device usage can include other applications.

A graph or embedding result contains a non-CUDA stage

Some graph clustering and embedding functions currently delegate stages to established R packages. This is documented rather than hidden. Use cuda_provenance(result) and the operation coverage guide to distinguish native CUDA tasks from hybrid workflows.

R torch is not required for the lightweight native CUDA path.