Registry / ai-ml / nvidia-cutlass-dsl-libs-base

nvidia-cutlass-dsl-libs-base

JSON →
library4.7.1pypypi✓ verified 24d ago

NVIDIA CUTLASS Python DSL (`nvidia-cutlass-dsl-libs-base`) provides a Pythonic interface for writing high-performance CUDA kernels using CUTLASS's CuTe library and tensor abstractions. It enables kernel development with automatic compilation to optimized PTX/SASS, offering performance comparable to hand-written CUDA C++ while enhancing developer productivity. Currently at version 4.4.2, the library is actively developed with frequent releases, often tied to new CUDA Toolkit versions and NVIDIA GPU architectures.

pip install nvidia-cutlass-dsl
INSTALL
IMPORT
SIG · NVIDIA-CUTLASS-DSL
N
nvidia-cutlass-dsl-libs-base
ai-mlpythonv4.7.1
Install
7.8s avg
Import
2293ms
Disk
586MB
Pass rate
4/ 10
Env Coverage4 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v4.7.1 · 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
musl
glibc
py 3.10
✕ build_error
✓ 8.37s
py 3.11
✕ build_error
✓ 7.83s
py 3.12
✕ build_error
✓ 7.6s
py 3.13
✕ build_error
✓ 7.53s
py 3.9
✕ build_error
✕ build_error
586MB installed
● package 586MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

cute
import cutlass.cute as cute
Primary import for the CuTe DSL functionalities.
from_dlpack
from cutlass.cute.runtime import from_dlpack
Used for seamless integration with DLPack-compatible frameworks like PyTorch.
cutlass
import cutlass_cppgen as cutlass
import cutlass
The legacy Python API package `cutlass` was renamed to `cutlass_cppgen` in CUTLASS 4.2.0 to disambiguate with the CuTe DSL.

This quickstart demonstrates how to define a simple element-wise addition CUDA kernel using the CuTe DSL. It shows the use of the `@cute.kernel` decorator, `cute.Tensor` for arguments, accessing thread indices with `cute.arch.thread_idx()`, converting PyTorch tensors using `from_dlpack`, compiling the kernel with `cute.compile`, and launching it on the GPU.

import cutlass.cute as cute import torch from cutlass.cute.runtime import from_dlpack @cute.kernel def elementwise_add_kernel( gA: cute.Tensor, gB: cute.Tensor, gC: cute.Tensor, shape: cute.Shape ): # Get thread index within the block tidx, _, _ = cute.arch.thread_idx() # Map thread index to global memory coordinate # Example: Simple 1D mapping for illustration # In real kernels, you'd use more sophisticated layouts and transforms val_layout = cute.make_layout(shape) coords = val_layout(tidx) # Perform element-wise addition if tidx < shape[0] * shape[1]: # Basic bounds check gC[coords] = gA[coords] + gB[coords] M, N = 1024, 512 A_torch = torch.randn(M, N, dtype=torch.float32, device='cuda') B_torch = torch.randn(M, N, dtype=torch.float32, device='cuda') C_torch = torch.zeros(M, N, dtype=torch.float32, device='cuda') # Convert torch tensors to CuTe Tensors mA = from_dlpack(A_torch).mark_layout_dynamic() mB = from_dlpack(B_torch).mark_layout_dynamic() mC = from_dlpack(C_torch).mark_layout_dynamic() # Compile the kernel compiled_kernel = cute.compile(elementwise_add_kernel, mA, mB, mC, (M, N)) # Launch the kernel # A simple block/grid configuration. More complex kernels would use CuTe's layout algebra. block_size = 256 # Example thread block size grid_size = (M * N + block_size - 1) // block_size # Ensure enough blocks compiled_kernel.launch(grid=[grid_size, 1, 1], block=[block_size, 1, 1]) # Verify (optional, requires torch.testing) try: torch.testing.assert_close(C_torch, A_torch + B_torch) print("Kernel executed successfully and results match!") except AssertionError as e: print(f"Verification failed: {e}")
Debug
Known issues
breakingThe legacy Python API package, previously named `cutlass` (e.g., `import cutlass`), was renamed to `cutlass_cppgen` in CUTLASS 4.2.0 (around September 2025). Direct imports of `cutlass` for the high-level C++ wrappers will fail.
fix
Update `import cutlass` to `import cutlass_cppgen as cutlass` for the high-level C++ interface. The `cutlass.cute` import for the CuTe DSL remains unchanged.
affects: 4.2.0 and later
gotchaCUTLASS Python DSL (including `nvidia-cutlass-dsl-libs-base`) has strict compatibility requirements with specific CUDA Toolkit and NVIDIA driver versions. Mismatches can lead to runtime errors or compilation failures.
fix
Always check the official CUTLASS documentation's 'Quick Start Guide' or 'Installation' section for the exact CUDA Toolkit and driver version required for your `nvidia-cutlass-dsl` version. For CUDA Toolkit 13.1, specific installation flags like `pip install nvidia-cutlass-dsl[cu13]` might be necessary.
affects: All versions
gotchaUnexpected CPU overhead was introduced in version 4.3.4 of the CuTe DSL.
fix
Users experiencing performance regressions should upgrade to version 4.3.5 or any later version (e.g., 4.4.x), where the issue was fixed.
affects: 4.3.4
gotchaInitial releases of CUTLASS DSL 4.0 had limited Python version support (e.g., Python 3.12 only). While newer versions expand this, ensure your Python version is explicitly supported.
fix
For `nvidia-cutlass-dsl` 4.4.2, Python 3.10 - 3.14 are supported. Always verify your Python version against the latest documentation for your specific CUTLASS DSL release.
affects: 4.0.0 - 4.4.1
gotchaVersion 4.4.1 fixed a segfault issue when using `tvm-ffi` on aarch64 systems.
fix
Users on aarch64 utilizing `tvm-ffi` should ensure they are running `nvidia-cutlass-dsl` version 4.4.1 or newer to avoid stability issues.
affects: Pre-4.4.1 (especially for aarch64 with `tvm-ffi`)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'cutlass'
This error often occurs due to an incorrect or corrupted installation, package conflicts (especially with `cutlass` vs `nvidia-cutlass-dsl`), or issues during upgrades/downgrades where `pip` leaves the environment in a broken state.
fix
First, uninstall all related CUTLASS DSL packages: `pip uninstall nvidia-cutlass-dsl nvidia-cutlass-dsl-libs-base nvidia-cutlass-dsl-libs-cu13 -y`. Then, reinstall the desired version, ensuring compatibility with your CUDA Toolkit: `pip install nvidia-cutlass-dsl` (or `pip install nvidia-cutlass-dsl[cu13]` for CUDA 13.x).
CUDA driver version is insufficient for CUDA runtime version
This error indicates a mismatch between your installed NVIDIA GPU driver version and the CUDA Toolkit version being used by `nvidia-cutlass-dsl-libs-base`. The driver version must be equal to or newer than the CUDA runtime version.
fix
Upgrade your NVIDIA GPU driver to the latest version compatible with your CUDA Toolkit. Check NVIDIA's documentation for the required driver version for your specific CUDA Toolkit. Alternatively, ensure your environment variables (like `LD_LIBRARY_PATH`) correctly point to the desired CUDA installation.
nvcc: Command not found
The CUDA compiler (`nvcc`) is not found in your system's PATH environment variable, which prevents `nvidia-cutlass-dsl-libs-base` from compiling CUDA kernels.
fix
Add the CUDA Toolkit's `bin` directory (e.g., `/usr/local/cuda/bin` or `/usr/local/cuda-X.Y/bin`) to your system's PATH environment variable. For example: `export PATH=/usr/local/cuda/bin:$PATH`.
TypeError: Cannot instantiate typing.Union
This issue typically arises from an incompatibility between `nvidia-cutlass-dsl` and newer Python versions, specifically Python 3.12, affecting the library's type introspection during JIT compilation or layout algebra operations.
fix
Ensure you are using a Python version officially supported by `nvidia-cutlass-dsl`, such as Python 3.10 or 3.11, as Python 3.12 might have compatibility issues with older library versions. Downgrading Python or upgrading the DSL library if a compatible version is available may resolve this.
ImportError: libcuda.so.1: cannot open shared object file: No such file or directory
This error indicates that the Python environment cannot locate the necessary CUDA runtime library (`libcuda.so.1`), often occurring on CPU-only machines, or when CUDA libraries are not properly installed, linked, or discoverable via `LD_LIBRARY_PATH`, particularly on AARCH64 systems.
fix
Verify that CUDA Toolkit is correctly installed and its library path (e.g., `/usr/local/cuda/lib64`) is included in the `LD_LIBRARY_PATH` environment variable. On AARCH64 or CPU-only setups, ensure the CUDA runtime components are present or consider if the library can be used in such environments. `export LD_LIBRARY_PATH=/path/to/cuda/lib64:$LD_LIBRARY_PATH`.
Upgrade
Version history
4.7.1latest on PyPI · released Aug 26, 2026
Audit
Dependencies
cuda-pythonrequiredRequired for CUDA integration and kernel launch.
torchoptionalRecommended for integration with PyTorch frameworks and running examples.
jaxoptionalRecommended for integration with JAX frameworks and running examples.
numpyrequiredCommon dependency for tensor operations, often used in examples.
networkxrequiredUnderlying dependency for some DSL functionalities.
pydotrequiredUnderlying dependency for some DSL functionalities.
scipyrequiredUnderlying dependency for some DSL functionalities.
treelibrequiredUnderlying dependency for some DSL functionalities.
Agent activity
9 hits · last 30 days
node
8
Resources
nvidia-cutlass-dsl-libs-base — pip install nvidia-cutlass-dsl-libs-base · libregistry