Registry /
ai-ml / nvidia-cutlass-dsl-libs-base
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
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.fixUpdate `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.fixAlways 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.fixUsers 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.fixFor `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.fixUsers 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.
fixFirst, 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.
fixUpgrade 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.
fixAdd 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.
fixEnsure 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.
fixVerify 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.