Back to Details

triton-operator-env-config

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Triton 算子开发环境配置

Triton Operator Development Environment Configuration

核心原则

Core Principles

必须按顺序执行环境检查，每个步骤依赖前一步的成功。
Environment checks must be performed in order, as each step depends on the success of the previous one.

前置步骤：获取最新配套要求（MANDATORY）

Prerequisite: Obtain the Latest Matching Requirements (MANDATORY)

配套版本可能更新，必须先获取官方最新文档。
MANDATORY - READ ENTIRE PAGE：访问并完整阅读官方在线文档 https://triton-ascend.readthedocs.io/zh-cn/latest/quick_start.html 和 https://triton-ascend.readthedocs.io/zh-cn/latest/installation_guide.html，获取最新的：
  • Python 版本要求
  • torch / torch_npu 版本要求
  • triton-ascend 版本要求
  • CANN 版本要求
  • 各组件版本对应关系
以文档中的版本要求为准，更新后续步骤中的版本号。
当前已知版本对应关系（截止 2026-03-26）：
Triton-Ascend 版本CANN 版本发布日期
3.2.08.5.0（推荐）2026/01/16
3.2.0rc48.3.RC22025/11/20
torch_npu 版本：2.7.1
Matching versions may be updated, so you must obtain the latest official documentation first.
MANDATORY - READ ENTIRE PAGE: Visit and fully read the official online documentation at https://triton-ascend.readthedocs.io/zh-cn/latest/quick_start.html and https://triton-ascend.readthedocs.io/zh-cn/latest/installation_guide.html to get the latest:
  • Python version requirements
  • torch / torch_npu version requirements
  • triton-ascend version requirements
  • CANN version requirements
  • Version correspondence of each component
Follow the version requirements in the documentation to update the version numbers in subsequent steps.
Currently known version correspondence (as of 2026-03-26):
Triton-Ascend VersionCANN VersionRelease Date
3.2.08.5.0 (Recommended)2026/01/16
3.2.0rc48.3.RC22025/11/20
torch_npu Version: 2.7.1

环境检查与配置流程

Environment Check and Configuration Process

1. CANN 环境配置（第一步）

1. CANN Environment Configuration (Step 1)

必须最先检查 CANN 环境
  1. 执行
    npu-smi info
    ，检查是否成功加载驱动
  2. 再执行
    which bisheng
    ，检查是否成功加载CANN环境获取到npuir编译器，应该输出路径
  3. 如果没有输出，尝试加载 CANN 环境：
    • 优先：
      source /usr/local/Ascend/cann/set_env.sh
    • 备选：
      source /usr/local/Ascend/ascend-toolkit/set_env.sh
  4. 再次执行第1步和第2步检查，如果不成功，需要等待用户去检查解决CANN的环境配置，可以提醒去https://www.hiascend.com/cann/download 上下载安装CANN
CANN environment check must be done first
  1. Execute 
    npu-smi info
    to check if the driver is loaded successfully
  2. Execute 
    which bisheng
    to check if the CANN environment is loaded and the npuir compiler is obtained, a path should be output
  3. If there is no output, try loading the CANN environment:
    • Priority: 
      source /usr/local/Ascend/cann/set_env.sh
    • Alternative: 
      source /usr/local/Ascend/ascend-toolkit/set_env.sh
  4. Perform step 1 and step 2 checks again. If unsuccessful, remind the user to check and resolve the CANN environment configuration, and suggest downloading and installing CANN from https://www.hiascend.com/cann/download

2. Python 版本检查

2. Python Version Check

如果遇到python问题，最优先使用miniconda创建环境解决
  1. 检查当前 python 的路径：
    which python3
  2. 若失败尝试执行：
    export PATH="/usr/bin:$PATH"
  3. 再次执行第1步检查，如果不成功，则需要提醒用户安装python，安装方式优先使用下面miniconda的方法
  4. 如果存在python3，检查python版本：
    python3 --version
    ，以官方 quick_start.md 文档中的要求为准
If encountering Python issues, use miniconda to create an environment as the first solution
  1. Check the current Python path: 
    which python3
  2. If failed, try executing: 
    export PATH="/usr/bin:$PATH"
  3. Perform step 1 check again. If unsuccessful, remind the user to install Python, preferring the miniconda method below
  4. If Python3 exists, check the Python version: 
    python3 --version
    , which must comply with the requirements in the official quick_start.md documentation

3. Python 环境安装（按需）

3. Python Environment Installation (On-Demand)

  1. 如果用户需要安装python环境，先使用
    conda init bash
    检查是否有conda环境，有则跳转第5步，如果没有则执行第2步安装
  2. 执行
    uname -m
    确认当前系统架构 如果系统架构为aarch64，执行：
    wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-aarch64.sh
    如果系统架构为x86_64，执行：
    wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
  3. 执行安装脚本：
    bash Miniconda3-latest-Linux-x86_64.sh
    或
    bash Miniconda3-latest-Linux-aarch64.sh
    ，按照提示安装后激活miniconda环境
  4. 检查是否成功安装miniconda环境：
    conda init bash
  5. 创建一个python环境，执行：
    conda create -n triton python=<官方要求版本>
  6. 激活python环境，执行：
    conda activate triton
  1. If the user needs to install a Python environment, first execute 
    conda init bash
    to check if a conda environment exists. If yes, jump to step 5; if no, execute step 2 to install
  2. Execute 
    uname -m
    to confirm the current system architecture If the system architecture is aarch64, execute: 
    wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-aarch64.sh
    If the system architecture is x86_64, execute: 
    wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
  3. Execute the installation script: 
    bash Miniconda3-latest-Linux-x86_64.sh
    or 
    bash Miniconda3-latest-Linux-aarch64.sh
    , activate the miniconda environment after installation as prompted
  4. Check if miniconda is installed successfully: 
    conda init bash
  5. Create a Python environment: 
    conda create -n triton python=<official required version>
  6. Activate the Python environment: 
    conda activate triton

4. torch 配置

4. torch Configuration

必须保证前面的步骤都成功
  1. 执行：
    pip list | grep "torch"
  2. 检查 torch / torch_npu 版本，以官方文档中的要求为准
  3. 如果版本不符合要求，按文档中的版本安装：
    • 先安装 torch：
      pip install torch==<官方要求版本>
    • 若报错 
      ERROR: No matching distribution found for torch==2.7.1+cpu
      ，尝试：
      bash
      pip install torch==2.7.1+cpu --index-url https://download.pytorch.org/whl/cpu
    • 再安装 torch_npu：
      pip install torch_npu==<官方要求版本>
  4. 检查torch环境是否配置成功：
    python3 -c "import torch; print(torch.__version__)"
  5. 运行一个简单的torch代码，检查是否成功加载npu设备：
    python3 -c "import torch; a = torch.randn(2, 3); print(a)"
    ，应该输出类似结果：
    tensor([[2.86, 1.0406, 1.5811], [0.8329, 1.0024, 1.3639]])
Ensure all previous steps are successful
  1. Execute: 
    pip list | grep "torch"
  2. Check the torch / torch_npu versions, which must comply with the requirements in the official documentation
  3. If versions do not meet requirements, install according to the documentation:
    • First install torch: 
      pip install torch==<official required version>
    • If encountering the error 
      ERROR: No matching distribution found for torch==2.7.1+cpu
      , try:
      bash
      pip install torch==2.7.1+cpu --index-url https://download.pytorch.org/whl/cpu
    • Then install torch_npu: 
      pip install torch_npu==<official required version>
  4. Check if the torch environment is configured successfully: 
    python3 -c "import torch; print(torch.__version__)"
  5. Run a simple torch code to check if the NPU device is loaded successfully: 
    python3 -c "import torch; a = torch.randn(2, 3); print(a)"
    , which should output results similar to: 
    tensor([[2.86, 1.0406, 1.5811], [0.8329, 1.0024, 1.3639]])

5. triton-ascend 配置

5. triton-ascend Configuration

  1. 执行：
    pip list | grep "triton"
  2. 社区 Triton 和 Triton-Ascend 不能同时存在：
    • 如果安装了原生的 triton，必须先卸载：
      pip uninstall triton
    • 如果同时安装了 triton-ascend，也需要先卸载，再重新安装
  3. 安装最新的 triton-ascend 包：
    pip install triton-ascend
  4. 如需安装 nightly 版本，参考：https://triton-ascend.readthedocs.io/zh-cn/latest/installation_guide.html#nightly-build
  1. Execute: 
    pip list | grep "triton"
  2. Community Triton and Triton-Ascend cannot coexist:
    • If native triton is installed, uninstall it first: 
      pip uninstall triton
    • If triton-ascend is also installed, uninstall it first, then reinstall
  3. Install the latest triton-ascend package: 
    pip install triton-ascend
  4. For installing the nightly version, refer to: https://triton-ascend.readthedocs.io/zh-cn/latest/installation_guide.html#nightly-build

环境验证（MANDATORY）

Environment Validation (MANDATORY)

用于确认当前终端环境可以正常执行triton算子。
MANDATORY - READ ENTIRE FILE：在执行验证前，必须完整阅读 
scripts/01-vector-add.py
。
执行验证：
bash
python3 <skill-dir>/scripts/01-vector-add.py
执行该算子样例后，如出现类似结果则表明其计算符合预期，difference为0.0则视为验证通过：
tensor([0.8329, 1.0024, 1.3639,  ..., 1.0796, 1.0406, 1.5811], device='npu:0')
tensor([0.8329, 1.0024, 1.3639,  ..., 1.0796, 1.0406, 1.5811], device='npu:0')
The maximum difference between torch and triton is 0.0
Used to confirm that the current terminal environment can execute Triton operators normally.
MANDATORY - READ ENTIRE FILE: Before performing the validation, you must fully read 
scripts/01-vector-add.py
.
Perform validation:
bash
python3 <skill-dir>/scripts/01-vector-add.py
After executing this operator sample, if results similar to the following appear, it indicates that the calculation meets expectations; a difference of 0.0 means the validation is passed:
tensor([0.8329, 1.0024, 1.3639,  ..., 1.0796, 1.0406, 1.5811], device='npu:0')
tensor([0.8329, 1.0024, 1.3639,  ..., 1.0796, 1.0406, 1.5811], device='npu:0')
The maximum difference between torch and triton is 0.0

故障处理

Troubleshooting

现象动作
torch 安装失败：No matching distribution found for torch==2.7.1+cpu尝试从 PyTorch 官方源安装：
pip install torch==2.7.1+cpu --index-url https://download.pytorch.org/whl/cpu
同时安装了原生 triton 和 triton-ascend先卸载原生 triton：
pip uninstall triton
，再重新安装 triton-ascend
找不到 C++ compiler安装编译器：
apt-get install g++
需要从源码编译时缺少依赖安装系统库：
sudo apt install zlib1g-dev clang-15 lld-15
（推荐 clang >= 15, lld >= 15）
已按上表重试仍失败保留完整终端报错与已执行的命令序列，便于本地或后续排查
SymptomAction
torch installation failed: No matching distribution found for torch==2.7.1+cpuTry installing from the official PyTorch source: 
pip install torch==2.7.1+cpu --index-url https://download.pytorch.org/whl/cpu
Both native triton and triton-ascend are installedUninstall native triton first: 
pip uninstall triton
, then reinstall triton-ascend
C++ compiler not foundInstall the compiler: 
apt-get install g++
Missing dependencies when compiling from sourceInstall system libraries: 
sudo apt install zlib1g-dev clang-15 lld-15
(clang >= 15, lld >= 15 is recommended)
Still failed after retrying according to the above tableKeep complete terminal error messages and the sequence of executed commands for local or subsequent troubleshooting

反模式清单（NEVER）

Anti-Pattern List (NEVER)

  • ❌ 跳过阅读官方在线文档获取最新配套要求
  • ❌ 跳过 CANN 环境检查直接配置 Python
  • ❌ 使用不符合官方要求的 Python / torch 版本
  • ❌ 同时安装原生 triton 和 triton-ascend
  • ❌ 不进行环境验证就开始开发
  • ❌ 在不同终端会话中分步执行（必须在同一终端）
  • ❌ Skip reading the official online documentation to obtain the latest matching requirements
  • ❌ Skip CANN environment check and directly configure Python
  • ❌ Use Python / torch versions that do not meet official requirements
  • ❌ Install both native triton and triton-ascend at the same time
  • ❌ Start development without environment validation
  • ❌ Execute steps in different terminal sessions (must be in the same terminal)

检查清单

Checklist

  • 已阅读官方在线文档获取最新配套要求？
  • CANN 环境加载成功（npu-smi info 和 which bisheng 有输出）？
  • Python 版本符合官方要求？
  • torch / torch_npu 版本符合官方要求？
  • triton-ascend 已安装（原生 triton 已卸载）？
  • 环境验证通过（01-vector-add.py 运行成功）？
  • Have you read the official online documentation to obtain the latest matching requirements?
  • Is the CANN environment loaded successfully (output from 
    npu-smi info
    and 
    which bisheng
    )?
  • Does the Python version meet official requirements?
  • Do the torch / torch_npu versions meet official requirements?
  • Has triton-ascend been installed (native triton has been uninstalled)?
  • Has the environment validation passed (
    01-vector-add.py
    runs successfully)?

注意事项

Notes