Install & Compatibility
Where this runs
tested against v12.5.10.65 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
build_error
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 9.3s · import 0.000s · 574MB
572MB installed
● package 572MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
nvidia
✓ import nvidia
✗ import cupy.sparse
This quickstart demonstrates how a higher-level Python library like CuPy leverages `nvidia-cusparse-cu12` for GPU-accelerated sparse matrix operations. The `nvidia-cusparse-cu12` package itself does not expose direct Python APIs. This code checks for CUDA availability and performs a basic sparse matrix-vector multiplication using CuPy's sparse module.
import os
try:
import cupy as cp
import cupy.sparse as cps
import numpy as np
# Check for CUDA device
if cp.cuda.is_available():
print(f"CUDA is available. CuPy version: {cp.__version__}")
print(f"CUDA Device Name: {cp.cuda.Device().name}")
# Create a sparse matrix on CPU (SciPy format)
row = np.array([0, 1, 2, 0])
col = np.array([0, 1, 2, 1])
data = np.array([1, 2, 3, 4])
shape = (3, 3)
sparse_cpu = cps.csr_matrix((data, (row, col)), shape=shape)
print("\nCPU Sparse Matrix:\n", sparse_cpu.toarray())
# Transfer to GPU and perform a sparse matrix-vector multiplication
sparse_gpu = cps.csr_matrix(sparse_cpu, dtype=cp.float32) # cuSPARSE generally works with float32/64
vector_gpu = cp.array([1.0, 2.0, 3.0], dtype=cp.float32)
result_gpu = sparse_gpu @ vector_gpu
print("\nGPU Sparse Matrix-Vector Product (using cuSPARSE via CuPy):\n", result_gpu)
else:
print("CUDA is not available. Please ensure a compatible NVIDIA GPU and driver are installed.")
print("You may need to install cupy-cuda12x manually if using a specific CUDA version.")
except ImportError:
print("CuPy is not installed. To run this example, install CuPy compatible with CUDA 12:")
print("pip install cupy-cuda12x")
except Exception as e:
print(f"An error occurred: {e}")
Debug
Known issues
breakingMismatch between `nvidia-cusparse-cu12` version and the installed CUDA Toolkit or GPU driver can lead to `ImportError: undefined symbol` errors. This commonly occurs when `torch` or `tensorflow` dependencies request a specific `nvidia-cusparse-cu12` version that doesn't align with your system's CUDA setup. [18, 20, 21, 23]fixEnsure that the CUDA Toolkit version on your system, your GPU driver, and all `nvidia-*-cu12` Python packages (including `nvidia-cusparse-cu12`) are compatible. Check the version requirements of higher-level libraries (e.g., PyTorch, TensorFlow) and install `nvidia-cusparse-cu12` (and related `nvidia-*` packages) that match their stated CUDA compatibility.
affects: All versions
gotchaThe `nvidia-cusparse-cu12` package provides native C++ runtime libraries and does not expose a direct Python API for `cusparse` functions. Attempting to `import cusparse` directly or find Python bindings within this package will fail. [13, 15]fixInteract with cuSPARSE functionality through higher-level Python libraries that provide Pythonic interfaces and utilize these underlying native libraries, such as CuPy's `cupy.sparse` module, or sparse tensor operations in PyTorch and TensorFlow.
affects: All versions
gotchaFor CUDA 12.4 and later, the `cusparseSpMV` routine might cause invalid memory accesses if the output vector is not 16-byte aligned. This can lead to crashes or incorrect results. [24]fixEnsure that any device memory pointers passed to `cusparseSpMV` (or high-level library functions that wrap it) for output storage are 16-byte aligned. In C++/CUDA, `cudaMalloc` guarantees sufficient alignment. When interfacing from Python, this is usually handled by the wrapping library (e.g., CuPy), but manual `cudaMalloc` calls might require explicit alignment checks.
affects: 12.4.0.x and later (including 12.5.x)
gotchaThis library is distributed under an NVIDIA Proprietary Software License (LicenseRef-NVIDIA-Proprietary), which may have different terms and conditions compared to open-source licenses. [2]fixReview the NVIDIA Proprietary Software License to ensure compliance with its terms for redistribution, modification, and usage in commercial or proprietary applications.
affects: All versions
gotchaSome examples or tests bundled with `nvidia-cusparse-cu12` might require additional Python libraries, such as CuPy. If these dependencies are not installed, attempts to run these examples will result in an error indicating the missing module.fixEnsure that all dependencies required by the specific example or test being run are installed. Follow any installation instructions provided with the examples, such as `pip install cupy-cuda12x`.
affects: All versions
breakingThe `nvidia-cusparse-cu12` package (and other `nvidia-*` packages) on PyPI.org is a placeholder. Attempting to install it directly without configuring the NVIDIA Python Package Index will result in a `RuntimeError` during the build process, indicating the package is not found or is a placeholder. The package is hosted on NVIDIA's own PyPI.fixTo install `nvidia-cusparse-cu12` and similar NVIDIA packages, you must first install the `nvidia-pyindex` package or configure pip to use `https://pypi.nvidia.com` as an extra index URL. The recommended fix is to run: `pip install nvidia-pyindex` followed by `pip install nvidia-cusparse-cu12`.
affects: All versions
Upgrade
Version history
12.5.10.65latest on PyPI · released Jun 5, 2025
Audit
Dependencies
nvidia-nvjitlink-cu12requiredRequired for JIT LTO functionality, as indicated by PyPI dependencies and CUDA documentation for cuSPARSE.
cupy-cuda12xoptionalCommonly used Python library that provides a NumPy-compatible array interface on GPUs and utilizes cuSPARSE for sparse operations.
torchoptionalPopular deep learning framework that can leverage cuSPARSE for sparse tensor operations.
tensorflowoptionalAnother major deep learning framework that can utilize cuSPARSE for sparse operations.