TileLang 怎么安装？昇腾 NPU 与 NVIDIA GPU 两条路线的环境准备、pip 安装与验证

TileLang 有两条安装路线：NVIDIA GPU 走 pip install tilelang，昇腾 NPU 走 pip install tilelang-ascend。装之前要先把前置条件对齐——NVIDIA 侧是 Python ≥3.10、glibc 2.28、CUDA ≥10.0（或 pip 提供的 cu13）；昇腾侧是 CANN ≥8.3.RC1、torch-npu ≥2.6.0.RC1，并先 source set_env.sh。

本文只解决「装进环境、装完能跑」，按「前置条件 → 两条路线 → 装完验证」讲。包从哪下载、各渠道差别，见《TileLang 怎么下载》；装完要用的命令速查在《TileLang 命令大全》。

装 TileLang 之前要满足哪些前置条件？昇腾与 NVIDIA 对照

TileLang 在两条硬件路线上的前置条件不同：NVIDIA 侧要 Python ≥3.10、glibc 2.28 和可用的 CUDA 工具链（≥10.0，或用 pip 提供的 cu13）；昇腾侧要 CANN ≥8.3.RC1、torch-npu ≥2.6.0.RC1，并保证 ASCEND_HOME_PATH 已生效（来源、来源）。 逐项对照：

1. Python 版本（两条路线都要）。执行 python -V 确认不低于 3.10。预期结果：打印 Python 3.10.x 及以上；低于 3.10 先升级解释器，后面的 pip 步骤才成立。
2. C 运行库（NVIDIA 侧）。执行 ldd --version 看 glibc 版本，官方要求 2.28 及以上（来源）。预期结果：打印 2.28 或更高的版本号。
3. CUDA 工具链（NVIDIA 侧）。确认本机 CUDA ≥10.0，或改用 pip 提供的 CUDA 工具链。预期结果：nvcc --version 能报出与驱动兼容的版本；若没有本地工具链，就用官方 pip 提供的 cu13 构建，不必自己装 nvcc。
4. CANN 与 torch-npu（昇腾侧）。确认 CANN ≥8.3.RC1、torch-npu ≥2.6.0.RC1，然后 source /usr/local/Ascend/ascend-toolkit/set_env.sh。预期结果：echo $ASCEND_HOME_PATH 打印出昇腾工具链路径（来源）。

建议用独立虚拟环境。 无论哪条路线，先把 TileLang 装进 venv 或 conda 环境，避免与系统 Python 里已有的 torch 版本互相踩踏。

TileLang 两条路线分别怎么装？

NVIDIA 路线一条命令即可：pip install tilelang；昇腾路线装独立包：pip install tilelang-ascend，离线时改用官方 wheel 或先用 build_wheel_ascend.sh 自建（来源、来源）。 按路线选一条执行：

1. NVIDIA 路线：直接 pip 装。执行 pip install tilelang。预期结果：pip 挑一个与当前 Python 匹配的 wheel 装上，全程无需本地编译（来源）。
2. NVIDIA 路线：源码构建。git clone --recursive https://github.com/tile-ai/tilelang 后进目录，按需设置 USE_CUDA=ON、TVM_ROOT 等构建开关再编译安装。预期结果：得到一份与本地工具链精确匹配的构建，代价是编译耗时更长、依赖更全。
3. 昇腾路线：pip 装官方包。先 source set_env.sh 载入 CANN，再执行 pip install tilelang-ascend。预期结果：pip 从 PyPI 拉包并装完（来源）。
4. 昇腾路线：离线 wheel 或自建。离线时设 export ASCEND_HOME_PATH=/usr/local/Ascend/ascend-toolkit/latest 后 pip install tilelang-*.whl；要自己构建就 git clone --recursive https://github.com/tile-ai/tilelang-ascend 并执行 ./build_wheel_ascend.sh [--enable-llvm]，再装 dist/ 下的产物（来源）。

昇腾路线目前官方验证的是 A2 与 A3 两类 NPU，其它型号属尽力兼容；后端同时支持 Ascend C & PTO 与 AscendNPU IR 两条技术路线（来源）。

装完怎么验证 TileLang？import、版本号与 GEMM 示例

验证分两步：先 import 看解释器认不认，再跑一个真实 GEMM 看能不能编出 kernel 并跑出正确结果（来源）。

1. 确认导入与版本。执行 python -c "import tilelang; print(tilelang.__version__)"。预期结果：打印出版本号；报 ModuleNotFoundError 说明装到了另一个解释器，用 which python 与 pip -V 对齐后重装。
2. 跑 GEMM 示例。执行 cd examples/gemm && python example_gemm.py。预期结果：终端打印 Kernel Output Match!，说明 TileLang 能编译 kernel 且算出的结果与参考实现一致（来源）。
3. 确认硬件后端真的被用上。在示例脚本里把 tilelang.compile 的目标设成对应后端（NVIDIA 用 cuda，昇腾用其 Ascend 目标）再运行。预期结果：编译过程没有回退到 CPU 或纯 Python 路径，日志里能看到目标后端名称。

三步都过，才算把 TileLang 真正装好；只装完不验证，等于把问题推迟到第一次跑算子时才暴露。

TileLang 安装的注意事项

1. 分清两条路线，别混装。tilelang 与 tilelang-ascend 是面向不同硬件的两个包，同一环境里只需装匹配当前机器的那一个；两个都装容易在 import 时抢同一个模块名。
2. 昇腾侧别漏 set_env.sh。ASCEND_HOME_PATH 没生效时 pip 能装上，但编译 kernel 会失败——这是昇腾侧最常见的「装好了却跑不动」。
3. 前置条件不满足就别硬装。Python 低于 3.10、glibc 低于 2.28 的环境，装上也编译不过；先补齐前置再装，比装完再排查省事。
4. 想要新版本别急着切 nightly。升级、切 nightly 与回退的完整做法，见《TileLang 怎么更新》。

装好之后，日常会用到的编译命令、性能分析工具与构建期环境变量，整理在《TileLang 命令大全》；如果装完出问题要回退，走《TileLang 怎么卸载》先把环境清干净再重装。

来源：TileLang Installation Guide、tilelang-ascend · PyPI、tile-ai/tilelang-ascend GitHub repository