NVIDIA cuSPARSELt

0.8.1 verified Tue May 12 auth: no python install: stale quickstart: stale

NVIDIA cuSPARSELt is a high-performance CUDA library dedicated to general matrix-matrix operations in which at least one operand is a structured sparse matrix. It supports NVIDIA Sparse MMA tensor cores, mixed-precision computation, matrix pruning and compression functionalities, activation functions, and batched computation. The current version is 0.8.1, and the library has an active release cadence with frequent updates.

pip install nvidia-cusparselt-cu12

Common errors

error ERROR: Could not find a version that satisfies the requirement nvidia-cusparselt-cu12 (from versions: none) ↓

cause This error typically occurs when pip cannot find a compatible package version on PyPI for the current environment, often due to an unsupported Python version, OS, or a very new/private package not yet fully available or indexed.

fix

Ensure your Python and system environment are compatible with the nvidia-cusparselt-cu12 package, check for correct spelling, and verify if the package is available for your specific CUDA version and platform. You might need to specify a --index-url if it's hosted on a private repository or a specific NVIDIA index.

error ERROR: Could not build wheels for nvidia-cusparselt-cu12, which is required to install pyproject.toml-based projects ↓

cause This indicates that the installation process failed during the build phase, often due to missing system dependencies (like a C++ compiler or CUDA toolkit components), an incompatible CUDA driver, or environmental issues preventing compilation of the underlying C++/CUDA code.

fix

Install necessary build tools (e.g., build-essential on Linux), ensure the CUDA Toolkit is correctly installed and its paths are configured, and verify that your NVIDIA GPU drivers are up to date and compatible with the target CUDA version.

error ModuleNotFoundError: No module named 'cusparselt' ↓

cause While `nvidia-cusparselt-cu12` installs the underlying C++/CUDA library, this error occurs if a Python wrapper or binding that *uses* `cusparselt` is expected but not found or correctly installed, or if the user is trying to directly import a C++ library as a Python module.

fix

Ensure you are using a Python library that correctly wraps cusparselt and that it is properly installed. nvidia-cusparselt-cu12 primarily provides the CUDA library; a separate Python binding might be required to interact with it directly from Python, or it's used internally by other deep learning frameworks.

error CUDA_ERROR_NO_DEVICE: no CUDA-capable device is detected ↓

cause This is a common low-level CUDA runtime error, indicating that the system either lacks an NVIDIA GPU, the GPU drivers are not installed or are outdated, or the CUDA runtime cannot detect an available device for computation, which `cusparselt` requires.

fix

Verify that an NVIDIA GPU is present and correctly installed. Update your NVIDIA GPU drivers to the latest version. Ensure the CUDA Toolkit is installed and configured correctly, and that the GPU is recognized by the operating system.

Warnings

breaking Starting with cuSPARSELt v0.9.0 (a version newer than 0.8.1, but released by NVIDIA), support for CUDA 12.9 and the Jetson platform has been discontinued. Users on these configurations should ensure they use a compatible older version of cuSPARSELt. ↓

fix For CUDA 12.9 or Jetson platforms, use `nvidia-cusparselt-cu12 < 0.9.0` (e.g., `==0.8.1`). Review NVIDIA's cuSPARSELt Release Notes for specific compatibility details before upgrading.

gotcha A common footgun with NVIDIA CUDA libraries is ensuring compatibility between the installed CUDA Toolkit, GPU drivers, and the `cuXX` version suffix of the Python package. `nvidia-cusparselt-cu12` specifically requires a CUDA 11.2 toolkit or above and compatible drivers. Mismatches can lead to runtime errors or a failure to leverage the GPU. ↓

fix Always install the `nvidia-cusparselt-cuXX` package corresponding to your CUDA Toolkit version. Verify your CUDA driver and toolkit installation. For CuPy users, `cupy.show_config()` can help diagnose CUDA environment issues. You may also need to explicitly install `nvidia-cuda-runtime-cu12` if not automatically resolved.

gotcha Installing `nvidia-*-cu12` packages can sometimes lead to prolonged dependency resolution times with `pip`. This is due to the complex interdependencies among various NVIDIA CUDA Python wheels. ↓

fix For complex dependency graphs, consider pinning exact versions for NVIDIA packages in a `requirements.txt` file or using a dependency resolver with stricter constraints. Sometimes, specifying `--no-deps` for individual NVIDIA packages (if dependencies are managed manually) can speed up installation, but this is advanced usage.

gotcha Similar to its related library `cuSPARSE`, care must be taken with memory alignment. In `cuSPARSE` versions with CUDA 12.4, incorrect 16-byte alignment of output vectors in `cusparseSpMV` could lead to invalid memory accesses. While not explicitly documented for `cuSPARSELt` in Python, this highlights a potential low-level memory management consideration for direct buffer manipulation in sparse CUDA operations. ↓

fix When performing low-level operations or passing device memory pointers, ensure that output buffers are correctly allocated and aligned (e.g., to 16 bytes for `float` or `half` types) to prevent potential memory access errors. Use CUDA's memory allocation functions (`cudaMalloc`) which guarantee alignment. If using frameworks like NumPy/CuPy, ensure their buffer creation respects necessary alignments.

breaking NVIDIA Python packages like `nvidia-cusparselt-cu12` are often 'placeholder' packages on PyPI.org. They require `https://pypi.nvidia.com/` to be specified as an extra index URL to locate and download the actual pre-built wheels. Failure to provide this index URL or to reach the NVIDIA PyPI server will result in 'Didn't find wheel' errors during installation. ↓

fix When installing NVIDIA Python packages, always include `--extra-index-url https://pypi.nvidia.com/` in your `pip install` command. For example: `pip install --extra-index-url https://pypi.nvidia.com/ nvidia-cusparselt-cu12`. Ensure that `https://pypi.nvidia.com/` is reachable from your build environment.

Install compatibility stale last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) build_error - - - -

3.10 alpine (musl) - - - -

3.10 slim (glibc) wheel 6.5s - 344M

3.10 slim (glibc) - - - 344M

3.11 alpine (musl) build_error - - - -

3.11 alpine (musl) - - - -

3.11 slim (glibc) wheel 6.1s - 345M

3.11 slim (glibc) - - - 345M

3.12 alpine (musl) build_error - - - -

3.12 alpine (musl) - - - -

3.12 slim (glibc) wheel 5.6s - 337M

3.12 slim (glibc) - - - 337M

3.13 alpine (musl) build_error - - - -

3.13 alpine (musl) - - - -

3.13 slim (glibc) wheel 5.3s - 337M

3.13 slim (glibc) - - - 337M

3.9 alpine (musl) build_error - - - -

3.9 alpine (musl) - - - -

3.9 slim (glibc) wheel 6.6s - 343M

3.9 slim (glibc) - - - 343M

Imports

Low-level C bindings via 'nvidia.cusparselt' module
```
import nvidia.cusparselt # Primarily provides C-level bindings to the cuSPARSELt library, not a high-level Python API.
```
This package primarily provides low-level C bindings for the cuSPARSELt library and is generally consumed by other Python frameworks (e.g., CuPy, PyTorch) rather than offering a direct, high-level Python API for end-users. Direct programmatic use might involve interacting with internal _lib modules or CFFI/ctypes wrappers, which are not typically exposed as stable public APIs.

Quickstart stale last tested: 2026-04-24

The `nvidia-cusparselt-cu12` package provides low-level Python bindings to the NVIDIA cuSPARSELt library. It does not typically expose a high-level Python API for direct user interaction. This quickstart demonstrates how to verify that the package and its core CUDA runtime components can be imported successfully, indicating a correct installation in a compatible CUDA environment. Further usage usually involves integrating with frameworks like CuPy or PyTorch that utilize these low-level bindings.

import sys
import subprocess

def check_package(package_name):
    try:
        __import__(package_name)
        print(f"Successfully imported {package_name}")
    except ImportError:
        print(f"Failed to import {package_name}. Please ensure it's installed and your CUDA environment is correctly set up.")
        sys.exit(1)

# This package is primarily for providing underlying CUDA binaries
# for other libraries. A direct high-level API is not typically exposed.
# The primary quickstart is to ensure successful installation and importability.

print("Verifying nvidia-cusparselt-cu12 installation...")
check_package('nvidia.cusparselt')

# Additional checks for CUDA runtime components (optional, but good practice)
print("Verifying core NVIDIA CUDA runtime components...")
check_package('nvidia.cuda_runtime')

print("Installation verification complete. Ensure your CUDA-enabled applications can leverage cuSPARSELt.")