Environment Setup¶

Prerequisites¶

Before proceeding with the Allo installation, please follow the instructions on the MLIR-AIE website to install the required Vitis and XRT environment. Stop when you reach the “Install IRON for AMD Ryzen™ AI AIE Application” section as we need a separate process to install MLIR-AIE under the Allo environment.

Install from Source¶

Please follow the general instructions in Install from Source to install the latest LLVM project and the Allo package. In the following, we suppose you have already installed the LLVM project, cloned Allo repository and created the allo conda environment.

Below are the exact commands to set up the environment:

Step 1¶

Activate the allo conda environment

conda activate allo

Step 2¶

We depend on the MLIR-AIE project to compile the Allo IR to AIE. Install release 1.0

# Install IRON library and mlir-aie from a wheel
python3 -m pip install mlir_aie -f https://github.com/Xilinx/mlir-aie/releases/expanded_assets/v1.0
# Install Peano from a llvm-aie wheel
python3 -m pip install https://github.com/Xilinx/llvm-aie/releases/download/nightly/llvm_aie-19.0.0.2025041501+b2a279c1-py3-none-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl

Warning

The pinned llvm_aie nightly wheel above no longer exists, so the pip install command will fail. For a working MLIR-AIE v1.0 environment, use Docker Setup for MLIR-AIE v1.0.

Warning

The mlir_aie wheel requires manylinux_2_35, and some systems (e.g., those with glibc 2.34, confirmed by ldd --version) do not meet this requirement. This results in an installation failure such as:

ERROR: mlir_aie-0.0.1.2025042204+24208c0-cp312-cp312-manylinux_2_35_x86_64.whl is not a supported wheel on this platform.

Step 3¶

Enter the Allo repository and install.

Enter the scripts directory

cd scripts

Set up MLIR-AIE by running the setup script

source aie-setup.sh

Note

This will clone the mlir-aie repository and checkout to the commit corresponding to release 1.0.

By default, the repository is cloned under Allo’s root directory. To customize the installation directory, use the --clone-dir option.

source aie-setup.sh --clone-dir /customized/path/

After running the setup script, you may see the following message in the terminal:

>>> Please note: Each time you activate your environment, you need to export the following variables:
export PATH=/path/to/your/env/lib/python3.12/site-packages/mlir_aie/bin:$PATH
export MLIR_AIE_INSTALL_DIR=/path/to/your/env/lib/python3.12/site-packages/mlir_aie
export PEANO_INSTALL_DIR=/path/to/your/env/lib/python3.12/site-packages/llvm-aie
export MLIR_AIE_EXTERNAL_KERNEL_DIR=/path/to/mlir-aie/aie_kernels/
export RUNTIME_LIB_DIR=/path/to/mlir-aie/runtime_lib/
export PYTHONPATH=/path/to/your/env/lib/python3.12/site-packages/mlir_aie/python:$PYTHONPATH

You can copy the export commands listed here into your own script (e.g., /path/to/your/env/etc/conda/activate.d/setup.sh), so that these environment variables are automatically set whenever you activate your environment.

To build and install Allo, you may want to set up environment variables first to use a custom CMake and LLVM build. For example:

export PATH=/opt/cmake-3.31.5-linux-x86_64/bin:/opt/llvm-project/build/bin:$PATH
export LLVM_BUILD_DIR=/opt/llvm-project/build

Next, enter Allo’s root directory and install by running the following commands

python3 -m pip install -v -e .

Note

See Internal Setup (Cornell) for Zhang Group students.

Step 4¶

Setup Vitis and XRT.

Note

See Internal Setup (Cornell) for Zhang Group students.

Lastly, you can verify the AIE backend by running the following command under Allo’s root directory.

python3 tests/dataflow/aie/test_vector.py

Docker Setup for MLIR-AIE v1.0¶

The shihanfang/allo-ci:aie-v1.0 image provides a working MLIR-AIE v1.0 environment and is also used by the weekly AIE CI workflow. After installing the required XDNA driver and XRT, run the following commands at the root directory of your cloned Allo repository:

docker pull shihanfang/allo-ci:aie-v1.0
docker run --rm -it \
   --device /dev/accel/accel0:/dev/accel/accel0 \
   --ulimit memlock=-1 \
   -v "$(pwd):/ryzers/allo" \
   -w /ryzers/allo \
   shihanfang/allo-ci:aie-v1.0 bash

The cloned Allo repository will be mounted to /ryzers/allo inside the container.

Inside the container, enter /ryzers/allo and then activate the pre-configured environment and install Allo:

source activate allo
python3 -m pip install -v -e .

Verify that XRT can access the NPU:

xrt-smi examine

Lastly, you can verify the AIE backend by running the following command under Allo’s root directory.

python3 tests/dataflow/aie/test_vector.py

Internal Setup (Cornell)¶

For Zhang Group students, an internal shared setup is available.

For Users¶

If you only need to use Allo (not develop it), you can skip the installation steps above and use the pre-configured shared environment by activating it directly:

conda activate /opt/anaconda3/envs/allo-base

To verify, run the following command under Allo’s root directory:

python3 tests/dataflow/aie/test_vector.py

For Developers¶

If you need to build Allo from source, set up environment variables in Step 3 with the following commands.

export PATH=/opt/cmake-3.31.5-linux-x86_64/bin:/opt/llvm-project/build/bin:$PATH
export LLVM_BUILD_DIR=/opt/llvm-project/build

And set up Vitis and XRT in Step 4 by running the following commands.

source /opt/common/setup.sh

Lastly, to verify the installation, you can run the following command:

python3 tests/dataflow/aie/test_vector.py

If the unit tests pass, then the installation is successful. Otherwise, please contact us for help.