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
✓ 10.6s
py 3.11
✕ build_error
✓ 9.1s
py 3.12
✕ build_error
✓ 8.55s
py 3.13
✕ build_error
✓ 8.9s
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
kernel
✓ from cutlass.cute import kernel
Decorator for defining GPU kernel functions.
jit
✓ from cutlass.cute import jit
Decorator for defining host-side JIT-compiled functions.
from_dlpack
✓ from cutlass.cute.runtime import from_dlpack
For converting framework tensors (e.g., PyTorch) to CuTe tensors.
This quickstart demonstrates a simple element-wise addition kernel written using CuTe DSL. It defines a GPU kernel with `@cute.kernel` and a host-side launch function with `@cute.jit`. It also shows how to interoperate with PyTorch tensors using `cute.runtime.from_dlpack` to pass data to the JIT-compiled kernel. The example performs vector addition on CUDA, launches the kernel, and verifies the output against PyTorch's native operation.
import cutlass.cute as cute
import torch
@cute.kernel
def elementwise_add_kernel(gA: cute.Tensor, gB: cute.Tensor, gC: cute.Tensor):
# Get thread index (tidx) and block index (bidx)
tidx, _, _ = cute.arch.thread_idx()
bidx, _, _ = cute.arch.block_idx()
# Calculate global index (simple 1D mapping for demonstration)
# In a real kernel, this would involve more complex layout algebra
global_idx = bidx * cute.block_dim_x() + tidx
# Perform element-wise addition
if global_idx < gC.size():
gC[global_idx] = gA[global_idx] + gB[global_idx]
@cute.jit
def launch_add_kernel(A, B, C):
# Launch the kernel
num_elements = A.size()
threads_per_block = 256 # Example thread block size
blocks_per_grid = (num_elements + threads_per_block - 1) // threads_per_block
elementwise_add_kernel(
cute.runtime.from_dlpack(A),
cute.runtime.from_dlpack(B),
cute.runtime.from_dlpack(C)
).launch(
grid=[blocks_per_grid, 1, 1],
block=[threads_per_block, 1, 1]
)
if __name__ == '__main__':
# Create example PyTorch tensors on GPU
size = 1024 * 1024 # 1 million elements
A_torch = torch.randn(size, dtype=torch.float32, device='cuda')
B_torch = torch.randn(size, dtype=torch.float32, device='cuda')
C_torch = torch.empty_like(A_torch, device='cuda')
# Launch the CuTe DSL kernel
launch_add_kernel(A_torch, B_torch, C_torch)
# Verify results (optional, using torch for comparison)
C_expected = A_torch + B_torch
assert torch.allclose(C_torch, C_expected, atol=1e-5), "Results do not match!"
print("Kernel executed successfully and results verified.")
cutlass --version
Debug
Known issues
breakingNVIDIA CUTLASS Python DSL (CuTe DSL) is a distinct project from the older 'CUTLASS Python' (which was a Python interface for C++ kernels). Existing code relying on the older interface will not be compatible.fixRewrite kernels and host interaction using the CuTe DSL decorators (`@cute.kernel`, `@cute.jit`) and CuTe tensor abstractions. Refer to the 'Limitations' and 'FAQs' sections in the official documentation.
affects: 4.0.0 and later
gotchaThe DSL requires a specific NVIDIA CUDA Toolkit version. For example, version 4.4.2 supports Python 3.10-3.14 and requires CUDA Toolkit 12.0+ (with 13.1 recommended for latest features like GB300 and Hopper FMHA fixes). Incompatible toolkit versions can lead to performance regressions, compilation errors, or runtime issues.fixEnsure your installed CUDA Toolkit version is compatible with the `nvidia-cutlass-dsl` version. For CUDA Toolkit 13.1+, use `pip install nvidia-cutlass-dsl[cu13]`. Always check release notes for specific version requirements.
affects: All versions
gotchaCuTe DSL has design limitations regarding Python language semantics within JIT-compiled functions. Complex data structures like lists, tuples, or dictionaries passed as dynamic values are treated as static containers and cannot be modified at runtime inside kernels. Returning dynamic values from kernels is also currently limited.fixUnderstand and adhere to the DSL's programming model. Use primitive types (int, bool, float) as dynamic values. For complex data, use them for 'meta-programming' or configuration during compilation, not as modifiable runtime data within the kernel. Refer to the 'Limitations' documentation.
affects: All versions
gotchaOptional features like Apache TVM FFI, which improves PyTorch interoperability and reduces host overhead, require separate installation (`pip install apache-tvm-ffi torch-c-dlpack-ext`) and explicit enabling (e.g., via `enable_tvm_ffi=True` in `cute.runtime.from_dlpack` or by setting `CUTE_DSL_ENABLE_TVM_FFI=1` environment variable).fixInstall the required `tvm-ffi` packages and ensure TVM FFI is correctly enabled in your code or environment if you intend to use it.
affects: 4.3.0 and later
breakingAPI changes in `cutlass.cute.arch` functions (e.g., `fence_proxy`, `warp_redux_sync`, `atomic_add`, `load`, `store`) in CUDA Toolkit 13.1+ environments now require string literals instead of enum arguments.fixUpdate calls to affected `cute.arch` functions to pass string literals (e.g., `'Release'`, `'Acquire'`) instead of previous enum-like objects. Consult the `changelog` and documentation for specific function signatures.
affects: 4.4.0 and later (when used with CTK 13.1+)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'cutlass'
The `nvidia-cutlass-dsl` package or its internal components are not correctly installed, or the Python environment is corrupted, often after upgrades or downgrades of the package.
fixCompletely uninstall existing `nvidia-cutlass-dsl` packages and then reinstall the desired version: `pip uninstall nvidia-cutlass-dsl nvidia-cutlass-dsl-libs-base nvidia-cutlass-dsl-libs-cu13 -y && pip install nvidia-cutlass-dsl`. Specify the CUDA toolkit version if necessary, e.g., `pip install nvidia-cutlass-dsl[cu13]` for CUDA 13.1.
ImportError: libcuda.so.1: cannot open shared object file: No such file or directory
The NVIDIA CUDA driver or runtime libraries (like `libcuda.so.1` or `libcudart.so.X`) are not found in the system's library search paths, which can happen on CPU-only machines, systems without a proper CUDA installation, or when `LD_LIBRARY_PATH` is not configured correctly.
fixEnsure that NVIDIA GPU drivers and the CUDA Toolkit are installed on your system. Verify that the CUDA library directories (e.g., `/usr/local/cuda/lib64` or specific CUDA version paths) are included in the `LD_LIBRARY_PATH` environment variable or configured in the system's linker paths.
TypeError: Cannot instantiate typing.Union
This error arises when using `nvidia-cutlass-dsl` with Python 3.12, indicating a compatibility issue between the CuTe DSL's internal type introspection mechanisms and changes in Python's `typing` module in newer versions, affecting JIT compilation and layout algebra operations.
fixDowngrade your Python environment to a version known to be compatible with `nvidia-cutlass-dsl` (e.g., Python 3.10 or 3.11, as indicated by documentation or issue trackers). Alternatively, check for a newer release of `nvidia-cutlass-dsl` that explicitly supports Python 3.12.
cudaErrorInsufficientDriver
The installed NVIDIA GPU driver is either too old or incompatible with the specific CUDA Toolkit version that `nvidia-cutlass-dsl` requires for its operations, leading to a driver-runtime mismatch.
fixUpdate your NVIDIA GPU drivers to the latest version compatible with your operating system and the CUDA Toolkit version recommended or used by your `nvidia-cutlass-dsl` installation. In some cases, temporarily downgrading the `cuda-python` package might also alleviate conflicts.
FileNotFoundError: [Errno 2] No such file or directory: '.../cutlass_instantiations/' OR PermissionError: [Errno 13] Permission denied: '.../cutlass_instantiations'
The Just-In-Time (JIT) compilation process of `nvidia-cutlass-dsl` attempts to write generated kernel files or intermediate artifacts into a directory that is either non-existent or read-only, which is common in containerized environments like Docker or Kubernetes where the installed package directories are typically immutable.
fixConfigure the JIT compiler to use a writable cache directory for generated kernels by setting appropriate environment variables (e.g., `FLASHINFER_WORKSPACE_BASE` or similar if the library exposes such an option, or a general `CUTE_DSL_CACHE_DIR`). Alternatively, pre-compile the necessary kernels during the container image build process to avoid runtime JIT compilation into read-only paths.
Upgrade
Version history
4.7.1latest on PyPI · released Aug 26, 2026
Audit
Dependencies
torchoptionalRecommended for running examples and PyTorch interoperability.
jupyteroptionalRecommended for educational notebooks and development.
jax[cuda]optionalRecommended for JAX integration and examples (specific versions recommended).
apache-tvm-ffioptionalOptional for improved PyTorch interop and faster JIT function invocation.
torch-c-dlpack-extoptionalOptional, often installed alongside tvm-ffi for DLPack protocol integration.