NVIDIA CUDA NVRTC

Common errors

• nvrtc: error: failed to open libnvrtc-builtins.so.XX.X (Linux) or nvrtc: error: failed to open nvrtc-builtins64_XX.dll (Windows)

  cause The NVRTC runtime compilation library, specifically its built-ins component, cannot be found by the application, often due to incorrect `LD_LIBRARY_PATH` (Linux) or `PATH` (Windows) environment variables, or an incomplete/mismatched CUDA Toolkit installation.
  fix Ensure your `LD_LIBRARY_PATH` (Linux) or `PATH` (Windows) environment variable includes the directory where `libnvrtc-builtins.so` or `nvrtc-builtins64.dll` is located (e.g., `<CUDA_PATH>/lib64` or `<CUDA_PATH>/bin`), and that the installed `nvidia-cuda-nvrtc` package version matches your CUDA Toolkit version. For Python environments on Windows, explicitly installing `nvidia-cuda-nvrtc-cuXX` and `nvidia-cuda-runtime-cuXX` with matching major.minor versions via pip can help.

• RuntimeError: Could not find libnvrtc.so. Please make sure CUDA is installed.

  cause The Python application (e.g., PyTorch, JAX, CuPy) or an underlying CUDA component cannot locate the primary NVRTC shared library (`libnvrtc.so` on Linux, `nvrtc64_XX_0.dll` on Windows), typically due to missing or incorrectly configured environment variables or a partial CUDA installation.
  fix Verify that `libnvrtc.so` or `nvrtc64_XX_0.dll` exists within your CUDA Toolkit installation (e.g., `<CUDA_PATH>/lib64` or `<CUDA_PATH>/bin`) and ensure this path is included in `LD_LIBRARY_PATH` (Linux) or `PATH` (Windows). For Python environments, ensure `nvidia-cuda-nvrtc` and other `nvidia-cuda-runtime` packages are correctly installed and compatible with your CUDA version.

• NVRTC_ERROR_COMPILATION (or NVRTCError: NVRTC_ERROR_COMPILATION)

  cause NVRTC encountered an error during the runtime compilation of a CUDA C++ kernel, meaning the provided source code contains syntax errors, unsupported features for the target architecture, or other issues preventing successful PTX generation.
  fix Inspect the NVRTC compilation log (often dumped to stderr or available via `nvrtcGetProgramLog`) for specific error messages, which will point to issues in the CUDA C++ source code being compiled. Correct the identified errors in the kernel code.

• nvrtc: error: invalid value for --gpu-architecture (-arch)

  cause An unsupported or incorrect GPU architecture flag (e.g., `--gpu-architecture=compute_XX` or `-arch=sm_YY`) was passed to NVRTC during compilation, often when the specified architecture does not match the available GPU or the NVRTC version's supported targets.
  fix Ensure the `--gpu-architecture` or `-arch` flag matches the compute capability of your target GPU (e.g., `sm_86` for an RTX 3080) and is supported by your CUDA Toolkit and NVRTC version. You can find your GPU's compute capability using `nvidia-smi` or `deviceQuery` from the CUDA samples.

Warnings

• gotcha No direct Python API is exposed by this package. Unlike typical Python libraries, `nvidia-cuda-nvrtc` does not provide Python symbols or classes for direct interaction with NVRTC functions. Its sole purpose is to provide the underlying native shared libraries (`libnvrtc.so` on Linux, `nvrtc64_*.dll` on Windows) which other Python frameworks (like PyTorch, JAX, or Numba) or C/C++ applications will then load and use.
  Fix: Do not attempt to import or call functions directly from `nvidia-cuda-nvrtc`. Instead, ensure it's installed as a dependency for frameworks that utilize NVRTC (e.g., PyTorch, JAX, Numba, or `cuda-python` for `ctypes` bindings).
• gotcha Requires a compatible NVIDIA GPU driver and CUDA Toolkit. While `nvidia-cuda-nvrtc` provides the NVRTC library, it does not install the full CUDA Toolkit or a GPU driver. For actual GPU computation or full CUDA functionality, your system must have a compatible NVIDIA GPU, an installed NVIDIA driver, and potentially a full CUDA Toolkit if you are compiling custom CUDA code or using other CUDA features.
  Fix: Verify your system meets the hardware and software requirements for CUDA. Install the latest stable NVIDIA GPU driver and, if necessary, the corresponding CUDA Toolkit for your operating system.
• gotcha Version alignment with CUDA Toolkit is critical. The version of `nvidia-cuda-nvrtc` (e.g., 13.2.x) directly corresponds to a specific CUDA Toolkit version (e.g., CUDA 13.2). Mismatches between the `nvidia-cuda-*` packages, system CUDA installations, or the CUDA versions expected by dependent libraries can lead to runtime errors, linker issues, or unexpected behavior.
  Fix: Ensure all `nvidia-cuda-*` packages (e.g., `nvidia-cuda-runtime`, `nvidia-cuda-cupti`, etc.) are aligned to the same major and minor CUDA version. If a specific framework requires a particular CUDA version, install the corresponding `nvidia-cuda-*` packages.
• gotcha Implicit usage by dependent frameworks. Unlike many Python packages where you explicitly `import` and call functions, `nvidia-cuda-nvrtc` is typically consumed implicitly by higher-level machine learning frameworks or GPU computing libraries. You might not see direct references to it in your code, but its absence or incompatibility can cause failures in these frameworks.
  Fix: When troubleshooting CUDA-related issues in frameworks like PyTorch or JAX, always check the installed `nvidia-cuda-*` packages and their versions as they are foundational dependencies.

Install

• pip install nvidia-cuda-nvrtc Install the package

Quickstart

This package does not expose a direct Python API for NVRTC functions. Its primary purpose is to install the necessary native shared libraries (`libnvrtc.so` or `nvrtc64_*.dll`) that other Python libraries (like PyTorch, JAX, or Numba) or C/C++ applications can load and link against. The code below merely confirms the package is installed and provides a conceptual usage note.

print("The nvidia-cuda-nvrtc package has been installed.")
print("It provides native shared libraries for runtime CUDA compilation.")
print("Other libraries (e.g., PyTorch, JAX) will automatically use these libraries if compatible.")
# No direct Python API calls are available from this package itself.