Star177
359
代码
代码
Issues138
Pull Requests241
流水线
讨论
Wiki
分析
Star177
359
LLH_123Lfeat: The main branch depends on triton==3.5.0 and does not support Python 3.9;
047438cb创建于 5月11日历史提交

Installation Guide

Choose the appropriate installation method as needed and proceed to the corresponding steps:

  • Install via pip: Select this option if you intend to use the pip package of Triton-Ascend directly. Please proceed to the next step to complete the prerequisite configuration in Environment Preparation, then perform the pip installation.
  • Install from source: Select this option for developers working with the Triton-Ascend source code. Please proceed to the next step to complete the prerequisite configuration in Environment Preparation, then choose either Quick Installation or Manual Installation.
  • Install via Docker: No environment preparation required. You may directly proceed to Build with Docker.

Preparing the Environment

Python Version Requirements

Triton-Ascend requires Python 3.9 to 3.11.

Installing CANN

Compute Architecture for Neural Networks (CANN) is a heterogeneous compute architecture developed by Ascend for AI scenarios. It plays a pivotal bridging role: providing upward integration with multiple AI frameworks (including MindSpore, PyTorch, and TensorFlow), while offering downward support for AI processors and programming. This establishes it as a key platform for improving the computing efficiency of Ascend AI processors.

You can visit the Ascend community website, and install and configure CANN according to the provided software installation guide. Developers can select the CANN version, product series, CPU architecture, operating system, and installation method to find the corresponding installation commands.

During the installation, select one of the following CANN versions in {version}. It is advisable to download and install version 8.5.0.

  • Note: If the installation path is not specified, software will be installed in the default path. The default installation paths are as follows: For the root user, the path is /usr/local/Ascend. For non-root users, the path is ${HOME}/Ascend, where ${HOME} indicates the current user's directory. The preceding environment variable configurations take effect only in the current window. You can add the source ${HOME}/Ascend/ascend-toolkit/set_env.sh command to the environment variable configuration file (such as the .bashrc file) as required.

CANN version:

  • Commercial edition
Triton-Ascend Version CANN Commercial Version CANN Release Date
3.2.1 CANN 9.0.0 2026/04/30
3.2.0 CANN 8.5.0 2026/01/16
3.2.0rc4 CANN 8.3.RC2
CANN 8.3.RC1		 2025/11/20
2025/10/30
  • Community edition
Triton-Ascend Version CANN Community Version CANN Release Date
3.2.1 CANN 9.0.0 2026/04/30
3.2.0 CANN 8.5.0 2026/01/16
3.2.0rc4 CANN 8.3.RC2
CANN 8.5.0.alpha001
CANN 8.3.RC1		 2025/11/20
2025/11/12
2025/10/30

Installing torch_npu

The current torch_npu version is 2.7.1.

pip install torch_npu==2.7.1

Note: If ERROR: No matching distribution found for torch==2.7.1+cpu is displayed, you can manually install Torch and then install torch_npu.

pip install torch==2.7.1+cpu --index-url https://download.pytorch.org/whl/cpu

Installing Triton-Ascend Using Pip

Latest Stable Version

You can install the latest stable version of Triton-Ascend using pip.

pip install triton-ascend==3.2.1 --extra-index-url=https://triton-ascend.osinfra.cn/pypi/simple
  • Note: for Triton-Ascend 3.2.0 and earlier versions：Triton-Ascend and Triton cannot coexist.You need to uninstall the community Triton first before installing Triton-Ascend.
    For Triton-Ascend 3.2.1 and later versions.Triton-Ascend declares Triton as an installation dependency to mitigate the installation overwriting issue.When installing Triton-Ascend,the community Triton is installed first,and the Triton-Ascend overwrites the directory with the same name. This prevents the installation of triton from overwriting Triton-Ascend when other software packages that depend on Triton are installed. The reason why x86 and arm use different versions of the community Triton installation package is that the community provides the arm installation package only form version 3.2.1 onwards. Specifically,x86 depends on triton==3.2.0,and arm depends on triton==3.5.0.
pip uninstall triton
pip uninstall triton-ascend
pip install triton-ascend==3.2.1 --extra-index-url=https://triton-ascend.osinfra.cn/pypi/simple

Historical Stable Version

pip install triton-ascend==3.2.0

Installing Triton-Ascend Using the Source Code

If you need to develop or customize Triton-Ascend, you should install it by compiling from source. This method allows you to modify the source code according to your project requirements and build a customized version of Triton-Ascend.

Before building, you need to install the required build dependencies as outlined in Dependency Installation.

We recommend completing the source installation of Triton-Ascend using the Quick Installation method. If you have special requirements, such as no network access on the target machine, you can use Manual Installation instead.

System Requirements

Pytorch Version Recommended GCC version Recommended GLIBC version
PyTorch2.7.1 11.2.1 2.28
PyTorch2.8.0 13.3.1 2.28
PyTorch2.9.1 13.3.1 2.28
PyTorch2.10 13.3.1 2.28

Dependencies

Installing System Library Dependencies

Install zlib1g-dev, LLD and Clang. You can also install ccache to accelerate the build process.

  • Recommended version: Clang >= 15
  • Recommended version: LLD >= 15
Taking Ubuntu as an example:
sudo apt update
sudo apt install zlib1g-dev clang-15 lld-15
sudo apt install ccache # optional

Triton-Ascend depends heavily on zlib1g-dev. If you use the yum source, run the following installation command:

sudo yum install -y zlib-devel

Installing Python Dependencies

pip install ninja cmake wheel pybind11 # build-time dependencies

Quick Installation

git clone https://gitcode.com/Ascend/triton-ascend.git
cd triton-ascend
git checkout main

# Optional: If a pre-compiled LLVM is available locally, you can specify the path to avoid downloading the pre-built LLVM package.
# Skip this command if no local LLVM exists and execute the installation command directly.
export LLVM_SYSPATH=/path/to/LLVM

# Run the installation command
pip install -e python

Manual Installation - Building with LLVM

Triton uses LLVM 22 to generate code for GPUs and CPUs. Similarly, the BiSheng Compiler of Ascend depends on LLVM to generate NPU code. Therefore, you need to compile the LLVM source code. Pay attention to the specific LLVM version of dependencies. LLVM build supports two methods. You only need to follow either method.

Code preparation: Run the git checkout command to check out the specified LLVM version

git clone --no-checkout https://github.com/llvm/llvm-project.git
cd llvm-project
git checkout fad3272286528b8a491085183434c5ad4b59ab92
wget https://raw.gitcode.com/Ascend/triton-ascend/blobs/2b0a06eb21438359d6d0576b622e3bb5e0292d17/fad3272.patch
git apply fad3272.patch

Installing LLVM Using Clang

  • Step 1: We use Clang to install LLVM. Install Clang and LLD in the environment and specify their versions (Clang >= 15 and LLD >= 15 are recommended). If Clang, LLD, and ccache are not installed, run the following commands to install them:

    apt-get install -y clang-15 lld-15 ccache

  • Step 2: Set the environment variable LLVM_INSTALL_PREFIX to your target installation path.

    export LLVM_INSTALL_PREFIX=/path/to/llvm-install

  • Step 3: Run the following commands to build and install LLVM:

    cd $HOME/llvm-project # Path to the LLVM code pulled by git clone
mkdir build
cd build
cmake ../llvm \
  -G Ninja \
  -DCMAKE_C_COMPILER=/usr/bin/clang-15 \
  -DCMAKE_CXX_COMPILER=/usr/bin/clang++-15 \
  -DCMAKE_LINKER=/usr/bin/lld-15 \
  -DCMAKE_BUILD_TYPE=Release \
  -DLLVM_ENABLE_ASSERTIONS=ON \
  -DLLVM_ENABLE_PROJECTS="mlir;llvm;lld" \
  -DLLVM_TARGETS_TO_BUILD="host;NVPTX;AMDGPU" \
  -DLLVM_ENABLE_LLD=ON \
  -DCMAKE_INSTALL_PREFIX=${LLVM_INSTALL_PREFIX}
ninja install

  • Step 4: Need to cp FILECHECK to your target installation path:

    cp  {PATH_TO}/llvm_project/build/bin/FileCheck ${LLVM_INSTALL_PREFIX}/bin/FileCheck

Cloning Triton-Ascend

git clone https://gitcode.com/Ascend/triton-ascend.git && cd triton-ascend

Building Triton-Ascend

  1. Install the source code.

    • Step 1: Ensure that the target installation path of LLVM (${LLVM_INSTALL_PREFIX}) has been set in the [Building with LLVM] section.
    • Step 2: Ensure that Clang 15 or later, LLD 15 or later, and ccache have been installed.
    LLVM_SYSPATH=${LLVM_INSTALL_PREFIX} \
TRITON_BUILD_WITH_CCACHE=true \
TRITON_BUILD_WITH_CLANG_LLD=true \
TRITON_BUILD_PROTON=OFF \
TRITON_WHEEL_NAME="triton-ascend" \
TRITON_APPEND_CMAKE_ARGS="-DTRITON_BUILD_UT=OFF" \
python3 setup.py install

    Note 1: For the recommended GCC version, please refer to the earlier section "System Requirements". If the GCC version is earlier than 9.4.0, "ld.lld: error: unable to find library -lstdc++fs" may be reported, indicating that the linker cannot find the stdc++fs library. This library supports the file system features of versions earlier than GCC 9. In this case, you need to manually uncomment the related code snippet in the CMake file.

    triton-ascend/CMakeLists.txt

    if (NOT WIN32 AND NOT APPLE)
link_libraries(stdc++fs)
endif()

    After uncommenting the code snippet, rebuild the project to solve the problem.

Installation via Docker

We provide a Dockerfile to help you build a Docker environment image. During installation, the corresponding CANN Toolkit and Kernel packages will be automatically downloaded from the official CANN website. You need to specify the CANN-related parameters for your machine using --build-arg.

Parameter Name Default Value Available Options
CHIP_TYPE A3 A3, 910B
CANN_VERSION 9.0.0 (Recommended) 9.0.0, 8.5.0, 8.3.RC1, 8.3.RC2, 8.2.RC1, 8.2.RC2

You can check the NPU model on your system using the npu-smi command.

For the machines corresponding to different CHIP_TYPE options, refer to the table below:

Option No. CHIP_TYPE Value Corresponding Server/Product Series Typical Server Model
1 A3 Atlas A3 Training Series Atlas 900 A3 SuperPoD
2 A2 Atlas A2 Training Series Atlas 800T A2 
git clone https://gitcode.com/Ascend/triton-ascend.git && cd triton-ascend
docker build \
--build-arg CHIP_TYPE=A3 \
--build-arg CANN_VERSION=9.0.0 \
-t triton-ascend-image:latest -f ./docker/Dockerfile .

To start a container from this image, you can use the following command as a reference:

docker run -u 0 -dit --shm-size=512g --name=triton-ascend_container --net=host --privileged \
--security-opt seccomp=unconfined \
--device=/dev/davinci0 \
--device=/dev/davinci1 \
--device=/dev/davinci2 \
--device=/dev/davinci3 \
--device=/dev/davinci4 \
--device=/dev/davinci5 \
--device=/dev/davinci6 \
--device=/dev/davinci7 \
--device=/dev/davinci_manager \
--device=/dev/devmm_svm \
--device=/dev/hisi_hdc \
-v /usr/local/dcmi:/usr/local/dcmi \
-v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \
-v /usr/local/sbin/npu-smi:/usr/local/sbin/npu-smi \
-v /usr/local/Ascend/driver:/usr/local/Ascend/driver \
-v /home:/home \
-v /etc/ascend_install.info:/etc/ascend_install.info \
triton-ascend-image:latest \
/bin/bash

# Enter the container
docker exec -u root -it triton-ascend_container /bin/bash

Run the Triton example

Install the runtime dependencies. Refer to the following command:

  # Pull the triton-ascend source code repository and examples (optional; required to pull the source code repository when running examples without source code compilation and installation).
  git clone https://gitcode.com/Ascend/triton-ascend.git
  cd triton-ascend && pip install -r requirements_dev.txt

Run the 01-vector-add.py instance.

  # Set the CANN environment variables (for example, as the root user and with the default installation path /usr/local/Ascend).
  source /usr/local/Ascend/ascend-toolkit/set_env.sh
  # Run the tutorials example.
  python3 ./third_party/ascend/tutorials/01-vector-add.py

If an output similar to the following is displayed, the environment is correctly configured:

    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