Skip to navigation

Installation

View as Markdown

NVIDIA cuVS provides APIs for C, C++, Python, Java, Go, and Rust. Start with the language you plan to use; each guide separates package installation from source builds and calls out any language-specific setup.

All NVIDIA cuVS routine implementations live in the C++ core. For every non-C++ language binding, install both the C library (libcuvs_c) and the C++ library (libcuvs) unless the selected package explicitly bundles them.

CUDA GPU Requirements

Pre-compiled NVIDIA cuVS packages are available for Linux on x86_64 and aarch64. Native Windows support is not available at this time. On Windows, use WSL2 with GPU passthrough. See the CUDA-X for data science WSL2 guide.

Source builds and package installs require a supported NVIDIA GPU. For current source builds, use CUDA Toolkit 12.9 or newer and an Volta architecture GPU or newer, which means compute capability 7.0 or higher.

Language Guides

  • C: install or build the C API and libcuvs_c.
  • C++: install or build the C++ headers and libcuvs.
  • Python: install Python wheels or conda packages, or build the Python package from source.
  • Java: build the Java API and connect it to matching native NVIDIA cuVS libraries.
  • Go: install the Go module and configure CGO against native NVIDIA cuVS libraries.
  • Rust: install the Rust crate and configure native NVIDIA cuVS dependencies.

Build From Source

Most source builds use the repository build.sh script. The script wraps CMake, prepares install targets, and provides language-specific build targets. Each language guide shows the target most users need.

The common source-build prerequisites are:

  1. CMake 4.0 or newer.
  2. GCC 13.3 or newer.
  3. A Python 3 interpreter.
  • cuTile ( CUDA 13.1 or newer ): the cuda.tile Python package, tileiras and bin2c. With conda install cutile-python and cuda-tileiras; with pip install cuda-tile and cuda-toolkit[tileiras].
  1. CUDA Toolkit 12.9 or newer.
  2. For CUDA Toolkit 12:
  1. For CUDA Toolkit 13 or newer:
  • Turing architecture or better (Compute Capability >=7.5) with CUDA 13.x

Optional components have additional requirements:

  • Multi-node multi-GPU tests (--mnmg-tests):
    • UCX
    • UCXX
  • Benchmarks (bench-ann):
    • glog
    • openblas
    • nlohmann_json
    • On x86_64, for the DiskANN algorithms:
      • mkl-devel 2023
      • libaio
      • Boost 1.87 (libboost-devel)

Create a Build Environment

The recommended way to construct an environment with the dependencies required to build NVIDIA cuVS is to use conda with the repository environment YAML file:

conda env create --name cuvs -f conda/environments/all_cuda-133_arch-$(uname -m).yaml
conda activate cuvs

You may prefer mamba over conda for faster environment solves. The conda/environments directory also contains language-specific environment YAML files for narrower development environments. Conda is not required, but if you do not use it, install all required build dependencies explicitly before running build.sh.

Build the Standalone C Library with Docker

The standalone tarball is built with Docker so that it uses the supported toolchain versions and the build remains portable and reproducible across all supported installation platforms.

Use the standalone Docker build when you want a libcuvs_c.tar.gz archive that you can unpack and use to build your own C or C++ binaries for deployment or integration.

Prerequisites

  • Docker with support for the target platform: x86_64 or aarch64.
  • At least 16 GB of memory and 20 GB of free disk space available to Docker.
  • NVIDIA Container Toolkit and a GPU if you want to run GPU-dependent steps. The image is based on CUDA and may require GPU support at runtime.

Use the Helper Script

From the repository root, run:

# (optional) clean old build directories
rm -rf ./{build,c/build/,cpp/build}
# build
./build.sh tarball

The script builds the Docker image, runs the build in a container, writes the tarball to ./build/libcuvs_c.tar.gz, and copies it to ./libcuvs_c.tar.gz for CI artifact upload and convenience.

The helper accepts the following environment variables:

VariableDefaultPurpose
CUVS_TARBALL_CUDA_VERSION13.3.0CUDA version for the rapidsai/ci-wheel base image.
CUVS_TARBALL_PYTHON_VERSION3.14Python version for the rapidsai/ci-wheel base image.
CUVS_TARBALL_BUILD_OUTPUT_DIR./buildHost directory where the tarball is written.

CUDA and Python versions should match an existing rapidsai/ci-wheel tag. See https://hub.docker.com/r/rapidsai/ci-wheel/tags

For example:

CUVS_TARBALL_CUDA_VERSION=13.3.0 \
CUVS_TARBALL_PYTHON_VERSION=3.14 \
./build.sh tarball

To write the tarball to another directory, set CUVS_TARBALL_BUILD_OUTPUT_DIR:

$ CUVS_TARBALL_BUILD_OUTPUT_DIR="${PWD}/dist" ./build.sh tarball
$ find . -name 'libcuvs_c.tar.gz'
./dist/libcuvs_c.tar.gz
./libcuvs_c.tar.gz

To build and install the C library tests in the archive, pass --tarball-build-tests:

./build.sh tarball --tarball-build-tests

Tarball Contents

The archive contains the headers, libraries, CMake configuration, and license information needed to compile and link C or C++ applications against the standalone NVIDIA cuVS libraries.

Build and Run the Docker Image Manually

If you do not want to use the helper script, build the image directly from the repository root:

docker build \
-f Dockerfile.standalone \
--build-arg CUDA_VERSION="13.3.0" \
--build-arg PYTHON_VERSION="3.14" \
--build-arg RAPIDS_VERSION="$(head -1 ./VERSION | cut -d. -f1,2 )" \
-t cuvs-standalone-c:local \
.

This command builds a local image and tags it as cuvs-standalone-c:local.

Run the build in a container using that image and mount the repository plus an output directory:

mkdir -p build
docker run --rm \
-v "${PWD}:/workspace" \
-v "${PWD}/build:/build" \
cuvs-standalone-c:local

Mount another host directory at /build to change the output location:

mkdir -p "${PWD}/dist"
docker run --rm \
-v "${PWD}:/workspace" \
-v "${PWD}/dist:/build" \
cuvs-standalone-c:local

Pass --tarball-build-tests to include the C library tests:

mkdir -p build
docker run --rm \
-v "${PWD}:/workspace" \
-v "${PWD}/build:/build" \
cuvs-standalone-c:local --tarball-build-tests

Documentation Preview

The NVIDIA cuVS documentation is a Fern project in the repository’s fern directory. Fern requires Node.js 22 or newer. If the docs fail with an error such as SyntaxError: Unexpected token '.', check node --version and activate a newer Node.js runtime.

Run the local preview from the repository root:

fern/build_docs.sh dev

Fern serves the preview at http://localhost:3000 by default.

Run the Fern checks before publishing documentation changes:

fern/build_docs.sh check