CUDA Samples

Samples for CUDA Developers which demonstrates features in CUDA Toolkit. This version supports CUDA Toolkit 13.3.

Release Notes

This section describes the release notes for the CUDA Samples on GitHub only.

Change Log

Revision History

Getting Started

Prerequisites

Download and install the CUDA Toolkit for your corresponding platform. For system requirements and installation instructions of cuda toolkit, please refer to the Linux Installation Guide, and the Windows Installation Guide.

Getting the CUDA Samples

Using git clone the repository of CUDA Samples using the command below.

git clone https://github.com/NVIDIA/cuda-samples.git

Without using git the easiest way to use these samples is to download the zip file containing the current version by clicking the "Download ZIP" button on the repo page. You can then unzip the entire archive and use the samples.

Building CUDA Samples

Building CUDA Samples

The CUDA Samples are built using CMake. Follow the instructions below for building on Linux, Windows, and for cross-compilation to Tegra devices.

Linux

Ensure that CMake (version 3.20 or later) is installed. Install it using your package manager if necessary:

e.g. sudo apt install cmake

Navigate to the root of the cloned repository and create a build directory:

mkdir build && cd build

Configure the project with CMake:

cmake ..

Build the samples:

make -j$(nproc)

Run the samples from their respective directories in the build folder. You can also follow this process from and subdirectory of the samples repo, or from within any individual sample.

Windows

Language services for CMake are available in Visual Studio 2019 version 16.5 or later, and you can directly import the CUDA samples repository from either the root level or from any subdirectory or individual sample.

To build from the command line, open the x64 Native Tools Command Prompt for VS provided with your Visual Studio installation.

Navigate to the root of the cloned repository and create a build directory:

mkdir build && cd build

Configure the project with CMake - for example:

cmake .. -G "Visual Studio 16 2019" -A x64

Open the generated solution file CUDA_Samples.sln in Visual Studio. Build the samples by selecting the desired configuration (e.g., Debug or Release) and pressing F7 (Build Solution).

Run the samples from the output directories specified in Visual Studio.

Enabling On-GPU Debugging

NVIDIA GPUs support on-GPU debugging through cuda-gdb. Enabling this may significantly affect application performance as certain compiler optimizations are disabled in this configuration, hence it's not on by default. Enablement of on-device debugging is controlled via the -G switch to nvcc.

To enable cuda-gdb for samples builds, define the ENABLE_CUDA_DEBUG flag on the CMake command line. For example:

cmake -DENABLE_CUDA_DEBUG=True ...

Platform-Specific Samples

Some CUDA samples are specific to certain platforms, and require passing flags into CMake to enable. In particular, we define the following platform-specific flags:

• BUILD_TEGRA - for Tegra-specific samples

To build these samples, set the variables either on the command line or through your CMake GUI. For example:

cmake -DBUILD_TEGRA=True ..

Cross-Compilation for Tegra Platforms

Install the NVIDIA toolchain and cross-compilation environment for Tegra devices as described in the Tegra Development Guide.

Ensure that CMake (version 3.20 or later) is installed.

Navigate to the root of the cloned repository and create a build directory:

mkdir build && cd build

Configure the project with CMake, specifying the Tegra toolchain file. And you can use -DTARGET_FS to point to the target file system root path for necessary include and library files:

cmake .. -DCMAKE_TOOLCHAIN_FILE=../cmake/toolchains/toolchain-aarch64-linux.cmake -DTARGET_FS=/path/to/target/system/file/system

Build the samples:

make -j$(nproc)

Transfer the built binaries to the Tegra device and execute them there.

Cross Building for Automotive Linux Platforms from the DriveOS Docker containers

To build CUDA samples to the target platform from the DriveOS Docker containers, use the following instructions.

Mount the target Root Filesystem (RFS) in the container so that the CUDA cmake process has the correct paths to CUDA and other system libraries required to build the samples.

Create a temporary directory, <temp> is any temporary directory of your choosing, for example, you can use /drive/temp:

$ mkdir /drive/<temp>

Mount the filesystem by running the following command:

$ mount /drive/drive-linux/filesystem/targetfs-images/dev_nsr_desktop_ubuntu-24.04_thor_rfs.img /drive/temp

Configure the project by running the following cmake command:

$ mkdir build && cd build
$ cmake .. -DBUILD_TEGRA=True \
  -DCMAKE_CUDA_COMPILER=/usr/local/cuda/bin/nvcc \
  -DCMAKE_TOOLCHAIN_FILE=../cmake/toolchains/toolchain-aarch64-linux.cmake \
  -DTARGET_FS=/drive/temp \
  -DCMAKE_LIBRARY_PATH=/drive/temp/usr/local/cuda-13.1/thor/lib64/ \
  -DCMAKE_INCLUDE_PATH=/drive/temp/usr/local/cuda-13.1/thor/include/

Please note that the following libraries are not pre-installed in the DriveOS dev-nsr target filesystem: * libdrm-dev * Vulkan

This causes the cmake command to throw errors related to the missing files, and as a result, the related samples will not build in later steps. This issue will be addressed in a future DriveOS release.

To build the samples with ignore the error mentioned above, you can use --ignore-errors/--keep-going or comment out the comment out the corresponding add_subdirectory command in the CMakeLists.txt in the parent folder for the samples requiring Vulkan and libdrm_dev:

$ make -j$(nproc) --ignore-errors # or --keep-going

# In cpp/5_Domain_Specific/CMakeList.txt
# add_subdirectory(simpleGL)
# add_subdirectory(simpleVulkan)
# add_subdirectory(simpleVulkanMMAP)

# In cpp/8_Platform_Specific/Tegra/CMakeList.txt
# add_subdirectory(simpleGLES_EGLOutput)

QNX

Cross-compilation for QNX with CMake is supported in the CUDA 13.0 samples release and newer. An example build for the Tegra Thor QNX platform might look like this:

$ mkdir build
$ cd build

QNX_HOST=/path/to/qnx/host \
QNX_TARGET=/path/to/qnx/target \
cmake .. \
-DBUILD_TEGRA=True \
-DCMAKE_CUDA_COMPILER=/usr/local/cuda-13.3/bin/nvcc \
-DCMAKE_TOOLCHAIN_FILE=../cmake/toolchains/toolchain-aarch64-qnx.cmake \
-DCMAKE_LIBRARY_PATH=/usr/local/cuda-13.3/thor/targets/aarch64-qnx/lib/stubs/ \
-DCMAKE_INCLUDE_PATH=/usr/local/cuda-13.3/thor/targets/aarch64-qnx/include/

Forward Compatibility

To build samples with new CUDA Toolkit(CUDA 13.0 or later) and UMD(Version 580 or later) and old KMD(Version 550 or earlier)，you need to set the CMAKE_PREFIX_PATH for using new driver library, the command might like this:

cmake -DCMAKE_PREFIX_PATH=/usr/local/cuda/lib64/stubs/ ..

CUDA Python samples

The repository includes Python examples under the python/ directory. These samples are cuda.core–focused: they use CUDA Python, with cuda.core for devices, programs, launches, and memory, alongside NumPy, CuPy, or framework interop where each sample notes.

Layout (same themes as the C++ samples):

Directory	Contents
python/1_GettingStarted/	Introductory scripts (e.g. vectorAdd, deviceQuery, systemInfo, image blur with unified memory, NumPy vs CuPy).
python/2_CoreConcepts/	Algorithms and techniques (e.g. reductions, histograms, FFT, stream overlap, memoryResources, cudaGraphs, jitLtoLinking, tmaTensorMap).
python/3_FrameworkInterop/	Integration with PyTorch and TensorFlow.
python/4_DistributedComputing/	Multi-GPU, peer-to-peer, and IPC patterns (ipcMemoryPool).
python/Utilities/	Shared helpers imported by some samples.

How to run: The top-level CMake build does not compile these samples. For each sample, use a Python 3.10+ environment with a matching CUDA Toolkit (the samples target CUDA 13.x and document exact package pins in requirements.txt):

cd python/<category>/<sampleName>
pip install -r requirements.txt
python <sampleScript>.py

Use each sample’s README.md for prerequisites, CLI options, and expected output.

Install Samples

Installation Path Structure

The installation system automatically organizes samples into a structured directory layout based on: - Target Architecture: ${CMAKE_SYSTEM_PROCESSOR}, e.g. x64, aarch64, amd64, etc. - Target OS: linux, windows, darwin, qnx - Build Type: release, debug, etc.

The default installation path is: build/bin/${TARGET_ARCH}/${TARGET_OS}/${BUILD_TYPE}

Examples: - Linux x86_64 Release: build/bin/x64/linux/release - Linux aarch64 Release: build/bin/aarch64/linux/release - Windows amd64 Release: build/bin/amd64/windows/release

Customizing Installation Paths

You can customize the installation location using CMake variables during the configuration step:

• CMAKE_INSTALL_PREFIX: Changes the root installation directory (default: build/bin) cmake -DCMAKE_INSTALL_PREFIX=/custom/path .. This will install to: /custom/path/${TARGET_ARCH}/${TARGET_OS}/${BUILD_TYPE}

• CUDA_SAMPLES_INSTALL_DIR: Specifies the exact final installation directory (overrides the structured path) cmake -DCUDA_SAMPLES_INSTALL_DIR=/exact/install/path ..

Install Samples on Linux

Prerequisites: You must first configure the project with CMake as described in the Building CUDA Samples - Linux or [Building]section.

After configuring and building, install the samples:

cd build/
make install

Install Samples on Windows

Prerequisites: You must first configure the project with CMake as described in the Building CUDA Samples - Windows section.

Using Command Line

After configuring with CMake, build and install from the x64 Native Tools Command Prompt for VS:

cd build
cmake --build . --config Release
cmake --install . --config Release

Note: Replace Release with Debug if you want to install debug builds. For multi-configuration generators (like Visual Studio), the --config flag determines which build type to install.

Using Visual Studio IDE

Alternatively, open the generated solution file CUDA_Samples.sln in Visual Studio: 1. Select the desired configuration (Release or Debug) 2. Build the solution (F7 or Build > Build Solution) 3. Right-click on the INSTALL target under CMakePredefinedTargets in Solution Explorer 4. Select "Build"

Running All Samples as Tests

It's important to note that the CUDA samples are not intended as a validation suite for CUDA. They do not cover corner cases, they do not completely cover the runtime and driver APIs, are not intended for performance benchmarking, etc. That said, it can sometimes be useful to run all of the samples as a quick sanity check and we provide a script to do so, run_tests.py.

This Python3 script finds all executables in a subdirectory you choose, matching application names with command line arguments specified in test_args.json. It accepts the following command line arguments:

Switch	Purpose	Example
--dir	Specify the root directory to search for executables (recursively)	--dir ./build/cpp
--config	JSON configuration file for executable arguments	--config test_args.json
--output	Output directory for test results (stdout saved to .txt files - directory will be created if it doesn't exist)	--output ./test
--args	Global arguments to pass to all executables (not currently used)	--args arg_1 arg_2 ...
--parallel	Number of applications to execute in parallel.	--parallel 8

Application configurations are loaded from test_args.json and matched against executable names (discarding the .exe extension on Windows).

The script returns 0 on success, or the first non-zero error code encountered during testing on failure. It will also print a condensed list of samples that failed, if any.

There are three primary modes of configuration:

Skip

An executable configured with "skip" will not be executed. These generally rely on having attached graphical displays and are not suited to this kind of automation.

Configuration example:

"fluidsGL": {
    "skip": true
}

You will see:

Skipping fluidsGL (marked as skip in config)

Single Run

For executables to run one time only with arguments, specify each argument as a list entry. Each entry in the JSON file will be appended to the command line, separated by a space.

All applications execute from their current directory, so all paths are relative to the application's location.

Note that if an application needs no arguments, this entry is optional. An e