# cuVS Environment Setup

_This guide explains how to configure and verify a GPU-capable environment for running KDB-X cuVS workloads._

## Prerequisites

| **Component** | **Requirement** |
|---|---|
| **Operating System** | Linux kernel 4.18 or newer (Ubuntu 20.04+, RHEL 8+) |
| **GPU** | Ampere architecture or newer (e.g. A100/H100, 40 GB+ VRAM) recommended for large-scale datasets. VRAM requirements vary with index size |
| **GPU Driver** | NVIDIA driver ≥ 580 |
| **CPU** | x86-64 (AMD64) architecture |

> **Note — ARM not supported**
>
> ARM architectures (including Apple Silicon) are not supported.
>
## CUDA-capable GPUs

The host machine must have one or more CUDA-capable NVIDIA GPUs with at least 40 GB VRAM. To check for a compatible GPU, run:
```bash
lspci | grep -i nvidia
```

Example output:
```bash
38:00.0 3D controller: NVIDIA Corporation AD104GL [L4] (rev a1)
3a:00.0 3D controller: NVIDIA Corporation AD104GL [L4] (rev a1)
```

> **Note**
>
> If the command returns no results, contact your system administrator. For a full list of CUDA-capable GPUs, refer to the NVIDIA website: [CUDA GPU Compute Capability](https://developer.nvidia.com/cuda/gpus).
>
## Check existing drivers with `nvidia-smi`

To check whether NVIDIA drivers are already installed, run:
```bash
nvidia-smi
```

If drivers are installed, the command displays GPU information:
```bash
+-----------------------------------------------------------------------------------------+
| NVIDIA-SMI 590.48.01              Driver Version: 590.48.01      CUDA Version: 13.1     |
+-----------------------------------------+------------------------+----------------------+
| GPU  Name                 Persistence-M | Bus-Id          Disp.A | Volatile Uncorr. ECC |
| Fan  Temp   Perf          Pwr:Usage/Cap |           Memory-Usage | GPU-Util  Compute M. |
|=========================================+========================+======================|
|   0  NVIDIA L4                      Off |   00000000:38:00.0 Off |                    0 |
| N/A   38C    P0             27W /   72W |       0MiB /  23034MiB |      0%      Default |
+-----------------------------------------+------------------------+----------------------+
```

Check the output:

- **`nvidia-smi` not found** – NVIDIA GPU drivers are not installed. Refer to the [instructions](#driver-dependencies-and-cuda-compatibility) below.
- **No GPU listed** – no compatible NVIDIA GPU detected. cuVS cannot run on CPU-only systems.
- **Driver version less than 580** – driver is too old. Update to the latest version.

If driver version is 580 or higher, no further action is needed. You can skip the next section and proceed to [Install KDB-X and the cuVS Module](kdb-env.md).

## Driver dependencies and CUDA compatibility

The cuVS module requires NVIDIA driver ≥ 580. CUDA dependencies are installed automatically as part of the module installation — refer to [Install KDB-X and the cuVS Module](./kdb-env.md).

CUDA provides [backward compatibility](https://docs.nvidia.com/deploy/cuda-compatibility/why-cuda-compatibility.html), meaning a newer driver can run applications built with an older CUDA Toolkit. We recommend installing the latest driver. Use the following link to install the latest version for your OS:

* [Driver Installation Guide](https://docs.nvidia.com/datacenter/tesla/driver-installation-guide/index.html)

You must install drivers for a [compatible host OS](https://docs.nvidia.com/datacenter/tesla/driver-installation-guide/introduction.html#linux-system-requirements). For installation examples refer to:

* [Ubuntu OS Drivers](https://docs.nvidia.com/datacenter/tesla/driver-installation-guide/ubuntu.html)
* [Red Hat OS Drivers](https://docs.nvidia.com/datacenter/tesla/driver-installation-guide/red-hat-enterprise-linux.html)
