Skip to content

[Docs] Improve Installation Guide #1270

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
LeiWang1999 merged 2 commits into from
Nov 17, 2025
Merged

[Docs] Improve Installation Guide #1270

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
cd1fa7c
[Docs] Improve installation guide
SiriusNEO Nov 17, 2025
dd2ec08
address comments
SiriusNEO Nov 17, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
134 changes: 42 additions & 92 deletions docs/get_started/Installation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,25 +8,25 @@
- **Python Version**: >= 3.8
- **CUDA Version**: 12.0 <= CUDA < 13

The easiest way to install **tile-lang** is directly from PyPI using pip. To install the latest version, run the following command in your terminal:
The easiest way to install tilelang is directly from PyPI using pip. To install the latest version, run the following command in your terminal:

```bash
pip install tilelang
```

Alternatively, you may choose to install **tile-lang** using prebuilt packages available on the Release Page:
Alternatively, you may choose to install tilelang using prebuilt packages available on the Release Page:

```bash
pip install tilelang-0.0.0.dev0+ubuntu.20.4.cu120-py3-none-any.whl
```

To install the latest version of **tile-lang** from the GitHub repository, you can run the following command:
To install the latest version of tilelang from the GitHub repository, you can run the following command:

```bash
pip install git+https://github.com/tile-ai/tilelang.git
```

After installing **tile-lang**, you can verify the installation by running:
After installing tilelang, you can verify the installation by running:

```bash
python -c "import tilelang; print(tilelang.__version__)"
Expand All @@ -40,31 +40,37 @@ python -c "import tilelang; print(tilelang.__version__)"
- **Python Version**: >= 3.8
- **CUDA Version**: >= 10.0

```bash
docker run -it --rm --ipc=host nvcr.io/nvidia/pytorch:23.01-py3
```
If you prefer Docker, please skip to the [Install Using Docker](#install-using-docker) section. This section focuses on building from source on a native Linux environment.

To build and install **tile-lang** directly from source, follow these steps. This process requires certain pre-requisites from Apache TVM, which can be installed on Ubuntu/Debian-based systems using the following commands:
First, install the OS-level prerequisites on Ubuntu/Debian-based systems using the following commands:

```bash
apt-get update
apt-get install -y python3 python3-dev python3-setuptools gcc zlib1g-dev build-essential cmake libedit-dev
```

After installing the prerequisites, you can clone the **tile-lang** repository and install it using pip:
Then, clone the tilelang repository and install it using pip. The `-v` flag enables verbose output during the build process.

> **Note**: Use the `--recursive` flag to include necessary submodules. Tilelang currently depends on a customized version of TVM, which is included as a submodule. If you prefer [Building with Existing TVM Installation](#using-existing-tvm), you can skip cloning the TVM submodule (but still need other dependencies).

```bash
git clone --recursive https://github.com/tile-ai/tilelang.git
cd tilelang
pip install . -v
```

If you want to install **tile-lang** in development mode, you can run the following command:
If you want to install tilelang in development mode, you can use the `-e` flag so that any changes to the Python files will be reflected immediately without reinstallation.

```bash
pip install -e . -v
```

> **Note**: changes to C++ files require rebuilding the tilelang C++ library. See [Faster Rebuild for Developers](#faster-rebuild-for-developers) below. A default `build` directory will be created if you use `pip install`, so you can also directly run `make` in the `build` directory to rebuild it as [Working from Source via PYTHONPATH](#working-from-source-via-pythonpath) suggested below.

(working-from-source-via-pythonpath)=

### Working from Source via `PYTHONPATH`

If you prefer to work directly from the source tree via `PYTHONPATH`, make sure the native extension is built first:

```bash
Expand All @@ -85,17 +91,21 @@ Some useful CMake options you can toggle while configuring:
- `-DUSE_ROCM=ON` selects ROCm support when building on AMD GPUs.
- `-DNO_VERSION_LABEL=ON` disables the backend/git suffix in `tilelang.__version__`.

We currently provide four methods to install **tile-lang**:
(using-existing-tvm)=

1. [Install Using Docker](#install-method-1) (Recommended)
2. [Install from Source (using the bundled TVM submodule)](#install-method-2)
3. [Install from Source (using your own TVM installation)](#install-method-3)
### Building with Existing TVM Installation

(install-method-1)=
If you already have a compatible TVM installation, use the `TVM_ROOT` environment variable to specify the location of your existing TVM repository when building tilelang:

### Method 1: Install Using Docker (Recommended)
```bash
TVM_ROOT=<your-tvm-repo> pip install . -v
```

(install-using-docker)=

For users who prefer a containerized environment with all dependencies pre-configured, **tile-lang** provides Docker images for different CUDA versions. This method is particularly useful for ensuring consistent environments across different systems and is the **recommended approach** for most users.
## Install Using Docker

For users who prefer a containerized environment with all dependencies pre-configured, tilelang provides Docker images for different CUDA versions. This method is particularly useful for ensuring consistent environments across different systems.

**Prerequisites:**
- Docker installed on your system
Expand Down Expand Up @@ -142,82 +152,17 @@ docker run -itd \
- `--name tilelang_b200`: Assigns a name to the container for easy management
- `/bin/zsh`: Uses zsh as the default shell

4. **Access the Container**:
4. **Access the Container and Verify Installation**:

```bash
docker exec -it tilelang_b200 /bin/zsh
```

5. **Verify Installation**:

Once inside the container, verify that **tile-lang** is working correctly:

```bash
# Inside the container:
python -c "import tilelang; print(tilelang.__version__)"
```

You can now run TileLang examples and develop your applications within the containerized environment. The Docker image comes with all necessary dependencies pre-installed, including CUDA toolkit, TVM, and TileLang itself.

**Example Usage:**

After accessing the container, you can run TileLang examples:

```bash
cd /home/tilelang/examples
python elementwise/test_example_elementwise.py
```

This Docker-based installation method provides a complete, isolated environment that works seamlessly on systems with compatible NVIDIA GPUs like the B200, ensuring optimal performance for TileLang applications.

(install-method-2)=

### Method 2: Install from Source (Using the Bundled TVM Submodule)

If you already have a compatible TVM installation, follow these steps:

1. **Clone the Repository**:

```bash
git clone --recursive https://github.com/tile-ai/tilelang
cd tilelang
```

**Note**: Use the `--recursive` flag to include necessary submodules.

2. **Configure Build Options**:

Create a build directory and specify your existing TVM path:

```bash
pip install . -v
```

(install-method-3)=

### Method 3: Install from Source (Using Your Own TVM Installation)

If you prefer to use the built-in TVM version, follow these instructions:

1. **Clone the Repository**:

```bash
git clone --recursive https://github.com/tile-ai/tilelang
cd tilelang
```

**Note**: Ensure the `--recursive` flag is included to fetch submodules.

2. **Configure Build Options**:

Copy the configuration file and enable the desired backends (e.g., LLVM and CUDA):

```bash
TVM_ROOT=<your-tvm-repo> pip install . -v
```

## Install with Nightly Version

For users who want access to the latest features and improvements before official releases, we provide nightly builds of **tile-lang**.
For users who want access to the latest features and improvements before official releases, we provide nightly builds of tilelang.

```bash
pip install tilelang -f https://tile-ai.github.io/whl/nightly/cu121/
Expand Down Expand Up @@ -253,23 +198,28 @@ Set `NO_TOOLCHAIN_VERSION=ON` to disable this.
### Run-time environment variables

<!-- TODO: tvm -->
TODO

## Other Tips

## IDE Configs
### IDE Configs

Building tilelang locally will automatically `compile_commands.json` file in `build` dir.
Building tilelang locally will automatically generate a `compile_commands.json` file in `build` dir.
VSCode with clangd and [clangd extension](https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.vscode-clangd) should be able to index that without extra configuration.

## Compile cache
### Compile Cache

`ccache` will be automatically used if found.
The default path of the compile cache is `~/.tilelang/cache`. `ccache` will be automatically used if found.

## Repairing wheels
### Repairing Wheels

If you plan to use your wheel in other environment,
it's recommend to use auditwheel (on Linux) or delocate (on Darwin)
it's recommended to use auditwheel (on Linux) or delocate (on Darwin)
to repair them.

## Faster rebuild for developers
(faster-rebuild-for-developers)=

### Faster Rebuild for Developers

`pip install` introduces extra [un]packaging and takes ~30 sec to complete,
even if no source change.
Expand Down
Loading