Build from Source

This page builds Triton-distributed-ascend and its two native dependencies. It assumes you have already completed Installation, including sourcing CANN’s set_env.sh.

There are four steps, in order:

Build LLVM (optional, only when no compatible prebuilt LLVM is available)
Build Triton-distributed-ascend
Build and install AscendNPU-IR
Build and install shmem

Steps 3 and 4 are not optional. AscendNPU-IR provides the compiler backend that lowers kernels to the NPU, and shmem provides the device-side communication runtime. Without both, the package imports but no distributed kernel will run.

Note

Every step below needs the CANN environment. Source it once per shell: source /usr/local/Ascend/ascend-toolkit/set_env.sh

1. Build LLVM (optional)

Skip this step unless the build reports that no compatible prebuilt LLVM is available, or you specifically need a custom LLVM. Building LLVM takes a long time and a lot of disk space.

Check out the pinned revision

The revision and patch are pinned. Using a different LLVM commit will not work.

git clone --no-checkout https://github.com/llvm/llvm-project.git
cd llvm-project
git checkout f6ded0be897e2878612dd903f7e8bb85448269e5
wget https://raw.githubusercontent.com/triton-lang/triton-ascend/2e69438a0a41a00ab72c7d46b44d97092cf2362c/third_party/ascend/patch/llvm_patch_f6ded0b.patch
git apply llvm_patch_f6ded0b.patch

Install Clang and LLD

Clang and LLD 15 or later are recommended:

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

Configure and build

Set the install prefix, then build:

export LLVM_INSTALL_PREFIX={PATH_TO}/llvm-install

cd {PATH_TO}/llvm-project
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

Copy the test tools

ninja install does not install FileCheck and llvm-lit, but the build expects them:

cp {PATH_TO}/llvm-project/build/bin/FileCheck ${LLVM_INSTALL_PREFIX}/bin/FileCheck
cp {PATH_TO}/llvm-project/build/bin/llvm-lit ${LLVM_INSTALL_PREFIX}/bin/llvm-lit

Pass LLVM_SYSPATH=${LLVM_INSTALL_PREFIX} to the build in the next step to use this LLVM.

2. Build Triton-distributed-ascend

Clone and initialize submodules

Submodules are initialized in two stages: the outer repository first, then the nested submodules inside 3rdparty/triton-ascend.

git clone https://gitcode.com/Ascend/Triton-distributed-ascend.git
cd Triton-distributed-ascend

git submodule update --init --depth=1
cd 3rdparty/triton-ascend
git submodule update --init --depth=1
cd ../../

Build and install

TRITON_USE_ASCEND=ON \
TRITON_BUILD_WITH_CLANG_LLD=ON \
TRITON_BUILD_PROTON=OFF \
TRITON_BUILD_LITTLE_KERNEL=OFF \
pip install ./python --no-build-isolation

If you built a custom LLVM in step 1, prepend LLVM_SYSPATH=${LLVM_INSTALL_PREFIX}.

Note

--no-build-isolation is required. The build reads the torch and pybind11 installs from your environment, and an isolated build environment would not have them.

Alternative build commands

For an editable install, which is what you want when working on the Python sources:

TRITON_USE_ASCEND=ON \
TRITON_BUILD_WITH_CLANG_LLD=ON \
TRITON_BUILD_PROTON=OFF \
TRITON_BUILD_LITTLE_KERNEL=OFF \
pip install -e ./python --verbose --no-build-isolation

To produce a wheel instead of installing:

TRITON_USE_ASCEND=ON \
TRITON_BUILD_WITH_CLANG_LLD=ON \
TRITON_BUILD_PROTON=OFF \
TRITON_BUILD_LITTLE_KERNEL=OFF \
pip wheel ./python --no-build-isolation

Build options

Variable	Meaning
`TRITON_USE_ASCEND=ON`	Build against triton-ascend instead of upstream Triton. Required.
`TRITON_BUILD_WITH_CLANG_LLD=ON`	Use Clang and LLD for linking
`TRITON_BUILD_PROTON=OFF`	Disable the Proton profiler build
`TRITON_BUILD_LITTLE_KERNEL=OFF`	Disable the mega-kernel build
`TRITON_PLUGIN_DIRS`	Path to the Triton plugin directory
`LLVM_SYSPATH`	Path to a custom LLVM install, from step 1

3. Build and install AscendNPU-IR

AscendNPU-IR is a separate repository. Clone it outside the Triton-distributed-ascend tree.

source /usr/local/Ascend/ascend-toolkit/set_env.sh
git clone https://gitcode.com/Ascend/AscendNPU-IR.git
cd AscendNPU-IR
git submodule update --init --depth=1
mkdir build
./build-tools/build.sh -o ./build -t --build-type Release \
  --apply-patches \
  --bisheng-compiler=$ASCEND_HOME_PATH/bin \
  --build-shmem-template

--bisheng-compiler points at the Bisheng compiler that ships with CANN, which is why ASCEND_HOME_PATH must be set. If it is empty, source set_env.sh again.

The build produces binaries in AscendNPU-IR/build/bin, which must be on your PATH at runtime:

export PATH={PATH_TO}/AscendNPU-IR/build/bin:$PATH

Add this to your shell profile so it persists across sessions.

4. Build and install shmem

shmem lives in the repository as a submodule and provides the device-side communication runtime.

source /usr/local/Ascend/ascend-toolkit/set_env.sh
cd Triton-distributed-ascend/3rdparty/shmem/
bash scripts/build.sh -python_extension
pip install dist/shmem-*.whl

The -python_extension flag builds the Python extension and produces a wheel in dist/.

For Ascend 950 hardware, add the SOC type:

bash scripts/build.sh -python_extension -soc_type Ascend950

Note

The default build targets the Ascend910B backend, which covers the A2 and A3 series. Run bash scripts/build.sh --help to see the other options, including RDMA support.

Verifying the build

Check that the package and the communication runtime both import:

python -c "import triton_dist; print(triton_dist.__file__)"
python -c "import shmem; print('shmem ok')"

Then run the Ascend unit tests, from the repository root:

pytest python/triton_dist/test/ascend/ -m dist

These tests exercise the communication primitives directly (barriers, wait/notify, symmetric memory addressing, put/get) and need at least two NPUs.

Troubleshooting

ASCEND_HOME_PATH is empty. You did not source set_env.sh in the current shell, or CANN is installed somewhere other than /usr/local/Ascend. Adjust the path and source it again.

Build fails looking for LLVM. No compatible prebuilt LLVM was found for your platform. Build LLVM using step 1 and pass LLVM_SYSPATH.

import triton_dist succeeds but kernels fail to compile. The AscendNPU-IR binaries are probably not on PATH. Confirm with which against a binary in AscendNPU-IR/build/bin.

Missing torch or pybind11 during the build. You likely dropped --no-build-isolation, or pip install -r requirements.txt was not run.

Next steps

Quick Start to run your first distributed kernel.