> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/NVIDIA/cutlass/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Install CUTLASS for C++ and Python development

CUTLASS provides both a C++ header-only library and a Python package. Choose the installation method that best fits your workflow.

## System requirements

### Minimum requirements

* **GPU**: NVIDIA GPU with compute capability 7.0 or higher (Volta architecture or newer)
* **CUDA Toolkit**: Version 11.4 or higher
* **Compiler**: C++17 compatible compiler
  * GCC 7.5.0 or higher (GCC 8.5.0 has known issues, use 7.5 or 9+)
  * Clang 7.0 or higher
  * MSVC 2019 or higher
* **CMake**: Version 3.19 or higher (for building examples and tests)
* **Python**: Version 3.8 or higher (for Python interface)

### Recommended requirements

* **CUDA Toolkit**: Version 12.8 or higher
* **GPU**: Hopper (H100, H200) or Blackwell (B200, B300, RTX 50 series)
* **Compiler**: GCC 11.2+ or Clang 14+
* **Python**: Version 3.9 or higher

<Note>
  CUTLASS 4.4.1 is optimized for CUDA 12.8+ and performs best on Hopper and Blackwell architectures with access to the latest Tensor Core features.
</Note>

## Supported platforms

### Operating systems

| Operating System | Compiler   | Status       |
| ---------------- | ---------- | ------------ |
| Ubuntu 18.04     | GCC 7.5.0  | Supported    |
| Ubuntu 20.04     | GCC 10.3.0 | Supported    |
| Ubuntu 22.04     | GCC 11.2.0 | Supported    |
| Windows          | MSVC 2019+ | Known issues |

<Warning>
  Windows builds have known issues in CUTLASS 4.x. The CUTLASS team is working on fixes. Linux is recommended for production use.
</Warning>

### GPU architectures

| Architecture    | Compute Capability | GPUs                | Min CUDA |
| --------------- | ------------------ | ------------------- | -------- |
| Volta           | 7.0                | V100, Titan V       | 11.4     |
| Turing          | 7.5                | RTX 20 series, T4   | 11.4     |
| Ampere          | 8.0, 8.6           | A100, RTX 30 series | 11.4     |
| Ada             | 8.9                | RTX 40 series, L40  | 11.8     |
| Hopper          | 9.0                | H100, H200          | 11.8     |
| Blackwell SM100 | 10.0               | B200                | 12.8     |
| Blackwell SM103 | 10.3               | B300                | 13.0     |
| Blackwell SM120 | 12.0               | RTX 50 series       | 12.8     |

<Note>
  Hopper and Blackwell architectures require the "a" suffix for architecture-accelerated features (e.g., `sm_90a`, `sm_100a`) to enable advanced Tensor Core instructions.
</Note>

## C++ installation

CUTLASS is a header-only library - no compilation or installation is required to use it in your projects.

<Steps>
  <Step title="Clone the repository">
    ```bash theme={null}
    git clone https://github.com/NVIDIA/cutlass.git
    cd cutlass
    ```

    Or download a specific release:

    ```bash theme={null}
    wget https://github.com/NVIDIA/cutlass/archive/refs/tags/v4.4.1.tar.gz
    tar -xzf v4.4.1.tar.gz
    cd cutlass-4.4.1
    ```
  </Step>

  <Step title="Set environment variables">
    Set `CUTLASS_PATH` for easy reference:

    ```bash theme={null}
    export CUTLASS_PATH=$(pwd)
    ```

    Set `CUDACXX` to point to your NVCC compiler:

    ```bash theme={null}
    export CUDACXX=/usr/local/cuda/bin/nvcc
    ```

    Add to your `.bashrc` or `.zshrc` for persistence:

    ```bash theme={null}
    echo 'export CUTLASS_PATH=/path/to/cutlass' >> ~/.bashrc
    echo 'export CUDACXX=/usr/local/cuda/bin/nvcc' >> ~/.bashrc
    source ~/.bashrc
    ```
  </Step>

  <Step title="Include in your project">
    Add CUTLASS headers to your include path:

    **Direct compilation:**

    ```bash theme={null}
    nvcc -I${CUTLASS_PATH}/include -std=c++17 your_code.cu -o your_program
    ```

    **CMake project:**

    ```cmake CMakeLists.txt theme={null}
    set(CUTLASS_PATH "/path/to/cutlass" CACHE PATH "CUTLASS root")
    include_directories(${CUTLASS_PATH}/include)
    ```

    **In your source code:**

    ```cpp theme={null}
    #include "cutlass/cutlass.h"
    #include "cutlass/gemm/device/gemm.h"
    ```
  </Step>

  <Step title="Verify installation (optional)">
    Build and run CUTLASS examples to verify your setup:

    ```bash theme={null}
    cd ${CUTLASS_PATH}
    mkdir build && cd build

    # Build for your GPU architecture (example: Ampere A100)
    cmake .. -DCUTLASS_NVCC_ARCHS=80

    # Build a basic example
    make 00_basic_gemm

    # Run the example
    ./examples/00_basic_gemm/00_basic_gemm
    ```

    Expected output:

    ```
    CUTLASS GEMM passed!
    ```
  </Step>
</Steps>

### CMake integration

For projects using CMake, you can use CUTLASS as an imported target:

```cmake theme={null}
find_package(NvidiaCutlass REQUIRED)

add_executable(my_app main.cu)
target_link_libraries(my_app PRIVATE nvidia::cutlass::cutlass)
```

Or install CUTLASS system-wide:

```bash theme={null}
cd ${CUTLASS_PATH}/build
cmake .. -DCUTLASS_ENABLE_HEADERS_ONLY=ON
sudo make install
```

### Architecture-specific builds

To compile for specific GPU architectures and reduce build time:

```bash theme={null}
# Single architecture (Ampere A100)
cmake .. -DCUTLASS_NVCC_ARCHS=80

# Multiple architectures
cmake .. -DCUTLASS_NVCC_ARCHS="80;89;90a"

# Hopper with architecture-accelerated features
cmake .. -DCUTLASS_NVCC_ARCHS=90a

# Blackwell datacenter
cmake .. -DCUTLASS_NVCC_ARCHS=100a
```

<Warning>
  Always use the "a" suffix for Hopper (`90a`) and Blackwell (`100a`, `103a`) when using Tensor Core features. Without the suffix, kernels will fail at runtime.
</Warning>

## Python installation

The CUTLASS Python interface is distributed as the `nvidia-cutlass` package.

<Steps>
  <Step title="Install from PyPI">
    The easiest way to install:

    ```bash theme={null}
    pip install nvidia-cutlass
    ```

    <Note>
      The package name is `nvidia-cutlass`. Other packages named `cutlass` are not affiliated with NVIDIA CUTLASS.
    </Note>
  </Step>

  <Step title="Install matching cuda-python">
    Ensure `cuda-python` version matches your CUDA Toolkit:

    ```bash theme={null}
    # For CUDA 11.8
    pip install cuda-python==11.8.0

    # For CUDA 12.0
    pip install cuda-python==12.0.0

    # For CUDA 12.8
    pip install cuda-python==12.8.0
    ```

    Check your CUDA version:

    ```bash theme={null}
    nvcc --version
    ```
  </Step>

  <Step title="Verify installation">
    Test the installation:

    ```python theme={null}
    import cutlass
    import numpy as np

    # Check version
    print(f"CUTLASS version: {cutlass.__version__}")

    # Run a simple GEMM
    plan = cutlass.op.Gemm(element=np.float16, layout=cutlass.LayoutType.RowMajor)
    A = np.ones((128, 128), dtype=np.float16)
    B = np.ones((128, 128), dtype=np.float16)
    C = np.zeros((128, 128), dtype=np.float16)
    D = np.zeros((128, 128), dtype=np.float16)

    plan.run(A, B, C, D)
    print("CUTLASS Python interface working!")
    ```
  </Step>
</Steps>

### Install from source

For development or to use the latest features:

<Steps>
  <Step title="Clone the repository">
    ```bash theme={null}
    git clone https://github.com/NVIDIA/cutlass.git
    cd cutlass
    ```
  </Step>

  <Step title="Set optional environment variables">
    ```bash theme={null}
    export CUTLASS_PATH=$(pwd)
    export CUDA_INSTALL_PATH=/usr/local/cuda
    ```

    If not set, these will be inferred automatically.
  </Step>

  <Step title="Install the package">
    For regular installation:

    ```bash theme={null}
    pip install .
    ```

    For development (changes reflect immediately):

    ```bash theme={null}
    pip install -e .
    ```
  </Step>

  <Step title="Install additional dependencies">
    The CUTLASS Python interface requires:

    ```bash theme={null}
    pip install cuda-python>=11.8.0 networkx numpy pydot scipy treelib
    ```

    These are installed automatically with `pip install nvidia-cutlass`.
  </Step>
</Steps>

### Python requirements

The CUTLASS Python interface has the following dependencies:

```toml theme={null}
[dependencies]
cuda-python>=11.8.0
networkx
numpy
pydot
scipy
treelib
```

Compatibility:

* **Python**: 3.8, 3.9, 3.10, 3.11
* **CUDA**: 11.8, 12.0, 12.1, 12.8, 13.0+
* **Platforms**: Linux (Ubuntu 18.04+), Windows (experimental)

## CuTe DSL installation

CuTe DSL is a Python interface for writing CUDA kernels.

<Steps>
  <Step title="Navigate to CuTe DSL directory">
    ```bash theme={null}
    cd ${CUTLASS_PATH}/python/CuTeDSL
    ```
  </Step>

  <Step title="Run the setup script">
    For CUDA 12.x:

    ```bash theme={null}
    ./setup.sh
    ```

    For CUDA 13.1:

    ```bash theme={null}
    ./setup.sh --cu13
    ```
  </Step>

  <Step title="Verify installation">
    ```python theme={null}
    import cutlass.cute as cute
    print(f"CuTe DSL version: {cutlass.__version__}")
    print(f"CUDA version: {cutlass.CUDA_VERSION}")
    ```
  </Step>
</Steps>

<Note>
  CuTe DSL requires CUTLASS C++ headers to be available. Set `CUTLASS_PATH` environment variable or install from the CUTLASS repository.
</Note>

### CuTe DSL features

* **CUDA Toolkit 13.1 support** with GB300 (SM103) support
* **Ahead-of-Time (AoT) compilation** for faster kernel loading
* **JAX integration** for use with JAX workflows
* **Experimental API** with fragment-free programming model
* **Automatic TMA descriptor generation** for Hopper/Blackwell

## Docker installation

The easiest way to get started with a complete environment:

```bash theme={null}
# Pull NVIDIA PyTorch container with CUDA and development tools
docker pull nvcr.io/nvidia/pytorch:23.08-py3

# Run container with GPU access
docker run --gpus all -it --rm \
  -v /path/to/cutlass:/workspace/cutlass \
  nvcr.io/nvidia/pytorch:23.08-py3

# Inside container, install CUTLASS Python
cd /workspace/cutlass
pip install .
```

This container includes:

* CUDA Toolkit
* cuDNN and cuBLAS libraries
* Python with PyTorch
* Development tools (gcc, cmake, etc.)

## Environment setup

### Recommended environment variables

Add these to your shell configuration for convenience:

```bash ~/.bashrc theme={null}
# CUTLASS paths
export CUTLASS_PATH=/path/to/cutlass
export CUDA_INSTALL_PATH=/usr/local/cuda
export CUDACXX=${CUDA_INSTALL_PATH}/bin/nvcc

# Add CUDA to path
export PATH=${CUDA_INSTALL_PATH}/bin:$PATH
export LD_LIBRARY_PATH=${CUDA_INSTALL_PATH}/lib64:$LD_LIBRARY_PATH

# For multi-GPU systems, specify visible devices
export CUDA_VISIBLE_DEVICES=0
```

### Build configuration

For CMake builds, create a configuration file:

```cmake cutlass_config.cmake theme={null}
# Target architectures
set(CUTLASS_NVCC_ARCHS "80;89;90a" CACHE STRING "")

# Enable examples and tests
set(CUTLASS_ENABLE_EXAMPLES ON CACHE BOOL "")
set(CUTLASS_ENABLE_TESTS ON CACHE BOOL "")

# Disable profiler for faster builds
set(CUTLASS_ENABLE_PROFILER OFF CACHE BOOL "")
```

Use with:

```bash theme={null}
cmake .. -C cutlass_config.cmake
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="CUDA Toolkit not found">
    Ensure CUDA is installed and `nvcc` is in your PATH:

    ```bash theme={null}
    which nvcc
    nvcc --version
    ```

    If not found, install CUDA from [NVIDIA's website](https://developer.nvidia.com/cuda-downloads).
  </Accordion>

  <Accordion title="Python import errors">
    Verify `cuda-python` matches your CUDA version:

    ```python theme={null}
    import cuda
    print(cuda.__version__)
    ```

    Reinstall with correct version:

    ```bash theme={null}
    pip uninstall cuda-python
    pip install cuda-python==12.8.0  # Match your CUDA version
    ```
  </Accordion>

  <Accordion title="Compiler version issues">
    Check your GCC version:

    ```bash theme={null}
    gcc --version
    ```

    GCC 8.5.0 has known issues. Use GCC 7.5 or 9+:

    ```bash theme={null}
    # Install alternative GCC version
    sudo apt-get install gcc-9 g++-9

    # Use with NVCC
    nvcc -ccbin g++-9 ...
    ```
  </Accordion>

  <Accordion title="CMake version too old">
    Install newer CMake:

    ```bash theme={null}
    # Remove old version
    sudo apt-get remove cmake

    # Install from Kitware
    wget https://github.com/Kitware/CMake/releases/download/v3.27.0/cmake-3.27.0-linux-x86_64.sh
    sudo sh cmake-3.27.0-linux-x86_64.sh --prefix=/usr/local --skip-license
    ```
  </Accordion>

  <Accordion title="Architecture mismatch errors">
    Ensure you're using the correct compute capability:

    ```bash theme={null}
    # Check GPU compute capability
    nvidia-smi --query-gpu=compute_cap --format=csv
    ```

    Use matching architecture flag:

    * 8.0 → `-gencode arch=compute_80,code=sm_80`
    * 9.0 → `-gencode arch=compute_90a,code=sm_90a` (note the "a")
    * 10.0 → `-gencode arch=compute_100a,code=sm_100a`
  </Accordion>

  <Accordion title="Windows build failures">
    Windows support is currently limited. For production use:

    * Use WSL2 with Ubuntu
    * Use Docker Desktop with Linux containers
    * Use a Linux system or VM
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Quick start guide" icon="rocket" href="/quickstart">
    Build your first GEMM kernel
  </Card>

  <Card title="C++ examples" icon="code" href="https://github.com/NVIDIA/cutlass/tree/main/examples">
    Explore example kernels
  </Card>

  <Card title="Python examples" icon="python" href="https://github.com/NVIDIA/cutlass/tree/main/examples/python">
    Python notebooks and scripts
  </Card>

  <Card title="Performance guide" icon="gauge-high" href="https://docs.nvidia.com/cutlass/latest/media/docs/cpp/profiler.html">
    Profile and optimize kernels
  </Card>
</CardGroup>

## Getting help

If you encounter issues:

* Check the [CUTLASS GitHub Issues](https://github.com/NVIDIA/cutlass/issues)
* Review the [CUTLASS documentation](https://docs.nvidia.com/cutlass)
* Ask questions on [NVIDIA Developer Forums](https://forums.developer.nvidia.com/c/ai/cutlass/)