NVIDIA/cuda-samples: how to install, build and run the CUDA sample set
Samples for CUDA Developers which demonstrates features in CUDA Toolkit
At a glance
- What is it?
- NVIDIA's cuda-samples repository is the official CMake-based collection of CUDA Toolkit examples, from deviceQuery to bandwidthTest. It is reference code for developers who already have a GPU and a toolkit, not a library you add to a project.
- Who is it for?
- Adopt it if you are learning CUDA, validating a new GPU or toolkit install, or want a working reference for a specific feature such as cuda-gdb debugging or Tegra cross-compilation. Do not adopt it as a dependency: nothing here is a library, and the samples are not maintained as production code.
- Can I use it commercially?
- Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
- Is it still maintained?
- Yes. The repository last received commits 12 days ago.
- What is it written in?
- Mainly C++, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 21, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
What NVIDIA/cuda-samples actually is, and who it is for
This is a repository of sample programs, not a framework. The README opens by describing it as "Samples for CUDA Developers which demonstrates features in CUDA Toolkit", and the current version supports CUDA Toolkit 13.4. Every directory under cpp/ is a self-contained example that you build and run to see a CUDA feature in action. The topics listed for the repository are cuda, cuda-driver-api, cuda-kernels and cuda-opengl, which maps to the categories you find inside cpp/: basic kernels, driver API usage, and graphics interop.
The audience is narrow and specific. You need an NVIDIA GPU, a matching CUDA Toolkit install, and a reason to read working CUDA C++ rather than a tutorial. If you are a Python developer looking for a package to import, this is the wrong repository. The python/ directory exists and pyproject.toml configures Ruff for it, but the primary language is C++ and the build system is CMake throughout.
The value is in the samples being official and versioned alongside the toolkit. When a new toolkit release changes an API, the samples move with it: the repository tagged v13.4 on 2026-09-09, following v13.3 in May 2026 and a v13.2 update earlier that month. That cadence is the strongest argument for using it as a reference rather than copying code from a blog post written against CUDA 11.
How the CMake layout works and why the architecture flag matters
The top-level CMakeLists.txt walks the cpp/ tree and adds each sample as a subdirectory. There is no single binary. You configure once at the repository root, build, and then run each sample from its own directory inside the build folder.
The one decision that shapes the whole build is CUDA architecture. By default, the README states, samples are compiled for all GPU architectures supported by the release. That is convenient and slow. If you only need one GPU, you override it, and the README says this reduces build time considerably. The flag is CMAKE_CUDA_ARCHITECTURES, and the value is your GPU's SM version, for example 90 for sm_90.
Standalone builds behave differently, and this trips people up. The README is explicit: "standalone builds have no top-level default", so if you configure CMake from inside a single sample directory you must pass an architecture yourself. The error message people search for, about failing to detect a default CUDA architecture, comes from exactly this situation. Passing -DCMAKE_CUDA_ARCHITECTURES=<arch> at configure time is the fix the README documents.
There is also a debug switch. On-GPU debugging through cuda-gdb is off by default because, as the README puts it, enabling it may significantly affect application performance since certain compiler optimizations are disabled. You turn it on with -DENABLE_CUDA_DEBUG=True, which adds the -G switch to nvcc.
Installing and running your first sample on Linux
There is nothing to install from a package index. You install the CUDA Toolkit first, following NVIDIA's platform guides, and then clone this repository. The README gives a single clone command.
git clone https://github.com/NVIDIA/cuda-samples.gitIf you prefer not to use git, the README points at the Download ZIP button on the repository page; you unzip the archive and use the samples from there.
Next, confirm CMake is present. The README requires version 3.20 or later and shows the Debian package as an example.
sudo apt install cmakeNow configure and build. From the repository root you create a build directory, run cmake, and then make. Passing your SM version keeps the build from targeting every supported architecture.
mkdir build && cd build
cmake -DCMAKE_CUDA_ARCHITECTURES=90 ..
make -j$(nproc)What you should see is a successful configure step that reports the CUDA compiler it found, followed by a long compile. When it finishes, the samples are in their respective directories under build/. Run them from there, not from the source tree.
To build only one sample, change directories into it and configure there. The architecture flag is not optional in this mode.
cd cpp/1_Utilities/deviceQuery
mkdir -p build && cd build
cmake -DCMAKE_CUDA_ARCHITECTURES=90 ..
makeOn Windows the README uses the x64 Native Tools Command Prompt for VS and a Visual Studio generator, for example cmake .. -G "Visual Studio 16 2019" -A x64, after which you open CUDA_Samples.sln and build with F7.
Tegra, DriveOS and the cross-compilation path
Platform-specific samples are gated behind CMake flags rather than being built by default. The README defines BUILD_TEGRA for Tegra-specific samples, enabled with -DBUILD_TEGRA=True.
Cross-compiling for Tegra requires the NVIDIA toolchain and cross-compilation environment, plus a toolchain file from the repository. The README's command passes the aarch64 toolchain file and a TARGET_FS pointing at the target file system root so the build can find the right headers and libraries.
cmake .. -DCMAKE_TOOLCHAIN_FILE=../cmake/toolchains/toolchain-aarch64-linux.cmake -DTARGET_FS=/path/to/target/system/file/systemBuilt binaries are then transferred to the Tegra device and executed there. This is a real constraint: you cannot run them on the build host.
The DriveOS path is more involved and the README is honest about why. Building from the DriveOS Docker containers means mounting the target root filesystem into the container so CMake resolves CUDA and system libraries correctly, then configuring with BUILD_TEGRA, an explicit CMAKE_CUDA_COMPILER, the toolchain file, TARGET_FS, and library and include paths under the mounted filesystem. The README notes that libdrm-dev and Vulkan are not pre-installed in the DriveOS dev-nsr target filesystem, which makes CMake error out and stops the related samples from building. It says the issue will be addressed in a future DriveOS release. The documented workarounds are make with --ignore-errors or --keep-going, or commenting out the relevant add_subdirectory lines for simpleGL, simpleVulkan and simpleVulkanMMAP in cpp/5_Domain_Specific/CMakeList.txt and the Tegra equivalents. That is a build that succeeds by skipping work, and you should treat it that way.
Where cuda-samples is the wrong tool
The samples are demonstration code. Nothing in the README describes them as a supported library, a stable API surface, or something you link against. If you copy a kernel out of a sample into production, you inherit whatever assumptions that sample makes about block size, grid shape and memory layout, and you have no compatibility guarantee across toolkit releases.
The build defaults work against you in two ways. Compiling for every supported architecture is the default at the top level, which the README itself frames as a trade-off against build time. And the standalone path has no default at all, so a developer who copies the single-sample instructions without the architecture flag gets a configure failure rather than a warning.
Debugging support is deliberately degraded. With ENABLE_CUDA_DEBUG the compiler disables optimizations, so any performance number you observe from a debug build is not the number the sample would produce normally. The README says this plainly, and it is worth repeating because it is easy to forget which build you are running.
Finally, if your goal is to learn CUDA concepts rather than run NVIDIA's code, the repository gives you no narrative. It gives you source files. The CUDA C Programming Guide is the companion document, and this repository assumes you are reading both.
How it compares with a general-purpose GPU portability layer
The obvious alternative for someone who wants GPU code that runs on more than one vendor is a portability layer such as SYCL or Kokkos, where a single kernel source targets multiple backends. The difference in approach is fundamental. cuda-samples is CUDA-specific by construction: it exists to demonstrate CUDA Toolkit features, including the driver API and OpenGL interop, and its build system calls nvcc directly through CMake's CUDA language support. A portability layer would abstract away the very APIs these samples are written to teach.
If cross-vendor portability is a requirement, cuda-samples cannot help you and was never intended to. If you are writing CUDA and want to see how a feature is meant to be used by the vendor that ships it, the portability layer is the wrong reference because it hides the vendor-specific path.
A second, less obvious comparison is against NVIDIA's own higher-level libraries. Where those give you a finished implementation, cuda-samples gives you the mechanism. That makes it useful for understanding what a library does underneath, and useless as a substitute for it.
Maintenance, licensing and what the repository does not tell you
The repository is not archived, and the last push was on 2026-09-09, which is recent. Releases track the toolkit: v13.4 on 2026-09-09, v13.3 on 2026-05-27, and a v13.2 update on 2026-05-13. That is a release cadence tied to CUDA Toolkit releases rather than to independent feature work, and it is the main signal that the samples stay in step with the compiler.
Upgrade cost is mostly reconfiguration. When you move to a new toolkit, you re-run CMake, and if you had pinned CMAKE_CUDA_ARCHITECTURES you may need to revisit that value for new hardware. The repository carries a CHANGELOG.md and a CONTRIBUTING.md, plus a .pre-commit-config.yaml and pyproject.toml with Ruff configuration for the python/ directory, so the Python portions have lint and format rules even though C++ is the primary language. Ruff is pinned to target-version py38 and a line length of 88, with S101, T20, S311, N806 and N999 ignored because the code is example code that prints and asserts.
Licensing is the part to check yourself. The repository reports a NOASSERTION licence identifier, which means GitHub could not map the LICENSE file to a standard SPDX identifier. There is a LICENSE file at the top level, and it is the authoritative text. Read it before you redistribute a sample or ship a derivative, and if the terms matter to your organisation, get them reviewed rather than inferring from the identifier. Nothing here is legal advice.
Editorial conclusion
Adopt it if you are learning CUDA, validating a new GPU or toolkit install, or want a working reference for a specific feature such as cuda-gdb debugging or Tegra cross-compilation. Do not adopt it as a dependency: nothing here is a library, and the samples are not maintained as production code. Before building, verify three things: that your CUDA Toolkit version matches the release the samples target (v13.4 supports CUDA Toolkit 13.4), that you know your GPU's SM version so you can pass CMAKE_CUDA_ARCHITECTURES, and that CMake is at least version 3.20, because the README states that as the floor. Start with cpp/1_Utilities/deviceQuery and compare its output against your hardware before you trust any other sample.
Frequently asked questions
How do I install NVIDIA/cuda-samples?
There is no package to install. You install the CUDA Toolkit for your platform first, then clone the repository with git clone https://github.com/NVIDIA/cuda-samples.git or download the ZIP from the repository page, and build it with CMake version 3.20 or later.
How do I run the CUDA samples on Ubuntu?
Install CMake, clone the repository, then create a build directory, run cmake with -DCMAKE_CUDA_ARCHITECTURES set to your GPU's SM version, and run make -j$(nproc). The README says to run the samples from their respective directories in the build folder.
What is cuda-samples?
It is NVIDIA's repository of sample programs that demonstrate features in the CUDA Toolkit, described in the README as "Samples for CUDA Developers". The current version supports CUDA Toolkit 13.4.
How do I use the CUDA samples?
Build the set with CMake from the repository root, or configure a single sample from inside its own directory. The README notes that standalone builds have no top-level default, so you must pass CMAKE_CUDA_ARCHITECTURES explicitly in that case.
Community notes