The fastest way to get MLIR-AIR is to install the prebuilt wheel — no source build, no CMake, no LLVM clone. Use this path unless you need to modify MLIR-AIR itself or run on an unsupported Python/platform.
Windows wheels are also published. This guide covers Linux only; Windows users will need to translate the
source/exportcommands to PowerShell equivalents.
AIR supports multiple backends — AIE (NPU / Versal AI Engines), GPU, and VCK5000. Backend dependencies are exposed as pip extras so you only install what you need. For the AIE backend on Ryzen™ AI, use the [aie] extra; pip reads the pinned mlir_aie==<version> and llvm-aie from the wheel’s metadata and resolves them from the additional --find-links pages.
python3 -m venv airenv
source airenv/bin/activate
pip install --upgrade pip
pip install 'mlir_air[aie]' \
-f https://github.com/Xilinx/mlir-air/releases/expanded_assets/latest-air-wheels \
-f https://github.com/Xilinx/mlir-aie/releases/expanded_assets/latest-wheels-3 \
-f https://github.com/Xilinx/llvm-aie/releases/expanded_assets/nightly
The [aie] extra pulls mlir_aie (pinned to the exact version this AIR wheel was tested against) and llvm-aie (the Peano backend compiler — nightly). The pinned mlir_aie version is shown on the release page.
To install AIR core only (e.g. when bringing your own backend), drop the [aie] extra and the last two -f flags.
pip show):
export MLIR_AIR_INSTALL_DIR=$(python3 -m pip show mlir_air | grep ^Location: | awk '{print $2}')/mlir_air
export MLIR_AIE_INSTALL_DIR=$(python3 -m pip show mlir_aie | grep ^Location: | awk '{print $2}')/mlir_aie
export PEANO_INSTALL_DIR=$(python3 -m pip show llvm-aie | grep ^Location: | awk '{print $2}')/llvm-aie
export PATH=$MLIR_AIR_INSTALL_DIR/bin:$MLIR_AIE_INSTALL_DIR/bin:$PATH
export PYTHONPATH=$MLIR_AIR_INSTALL_DIR/python:$MLIR_AIE_INSTALL_DIR/python:$PYTHONPATH
export LD_LIBRARY_PATH=$MLIR_AIR_INSTALL_DIR/lib:$MLIR_AIE_INSTALL_DIR/lib:$LD_LIBRARY_PATH
# Only if you have XRT installed:
source /opt/xilinx/xrt/setup.sh
air-opt --help
You can now jump to Running a Quick Example below.
We release both RTTI and no-RTTI variants so downstream projects can match their LLVM build configuration without having to rebuild MLIR-AIR from source.
| Tag | When to use |
|---|---|
latest-air-wheels |
Default. RTTI enabled. Use this for standalone development. The install command in step 2 above targets this tag. |
latest-air-wheels-no-rtti |
For integrating MLIR-AIR into a downstream project whose LLVM is built with -DLLVM_ENABLE_RTTI=OFF. Use the no-RTTI install snippet below. |
v*.*.* (e.g. v1.0.0) |
Pinned tagged release, for reproducible builds. Replace the find-links URL with .../expanded_assets/v<ver> and the package spec with mlir_air==<ver>. |
For the no-RTTI variant, point both find-links at the no-RTTI pages so pip resolves the matching mlir_aie:
pip install 'mlir_air[aie]' \
-f https://github.com/Xilinx/mlir-air/releases/expanded_assets/latest-air-wheels-no-rtti \
-f https://github.com/Xilinx/mlir-aie/releases/expanded_assets/latest-wheels-no-rtti \
-f https://github.com/Xilinx/llvm-aie/releases/expanded_assets/nightly
When mixing wheels into a downstream build, all three (mlir, mlir_aie, mlir_air) must agree on RTTI.
If the wheel install path doesn’t fit your needs, see the source-build instructions below.
This path builds MLIR-AIR from source but installs LLVM, MLIR-AIE, and Peano from prebuilt wheels — useful when you’re hacking on MLIR-AIR itself but don’t want to also rebuild its dependencies.
git clone https://github.com/Xilinx/mlir-air.git
cd mlir-air
sudo apt-get install -y ninja-build clang lld unzip
source utils/setup_python_packages.sh
Run the build script:
Without XRT (software-only build):
./utils/build-mlir-air-using-wheels.sh [build_dir] [install_dir]
With XRT (for hardware execution):
./utils/build-mlir-air-using-wheels.sh --xrt-dir <xrt_path> [build_dir] [install_dir]
Parameters:
--xrt-dir <xrt_path>: Path to your XRT installation (optional, only needed for hardware execution)[build_dir]: Build directory (optional, default: build)[install_dir]: Install directory (optional, default: install)The script will:
llvm-aie, which is used as a backend to generate AIE binariesmlir-aie dependencies from wheels--xrt-dir is providedsource utils/env_setup.sh [install_dir] $(python3 -m pip show mlir_aie | grep Location | awk '{print $2}')/mlir_aie $(python3 -m pip show llvm-aie | grep Location | awk '{print $2}')/llvm-aie my_install/mlir
This command automatically detects the installation directories of the mlir-aie and llvm-aie Python packages, and sets up environment variables for MLIR-AIR, MLIR-AIE, PEANO (llvm-aie compiler), Python, and MLIR libraries.
If you built with XRT support, also run:
source [xrt_dir]/setup.sh
This sets up the PATHs for XRT.
If you start a new terminal, you may need to re-source the above setup scripts as needed.
cd <build_dir> # default is 'build'
ninja install
ninja check-air-cpp
ninja check-air-mlir
ninja check-air-python
If you built with XRT support, you can also run XRT/hardware tests:
# Run LIT tests (set -DLLVM_EXTERNAL_LIT if needed)
lit -sv --time-tests --show-unsupported --show-excluded --timeout 600 -j5 test/xrt
# Run an individual test
lit -sv test/xrt/01_air_to_npu
# Run all xrt tests on device (may take a long time)
ninja check-air-e2e-peano
-DLLVM_EXTERNAL_LIT to the path of your lit executable.After building MLIR-AIR, you can try the i8 matrix multiplication example to verify your setup and understand the different compilation workflows. Matmul shapes are configurable in the Makefile.
This mode is useful for cross-compilation or development without hardware access. It generates intermediate compilation artifacts without requiring XRT to be installed:
cd programming_examples/matrix_multiplication/i8
make run4x4 COMPILE_MODE=compile-only
Expected output: Compilation completed successfully!
What this does:
xclbinutil needed)When to use:
If you have XRT and Ryzen AI hardware available, run the complete workflow:
cd programming_examples/matrix_multiplication/i8
make run4x4
Expected output: PASS!
What this does:
This is the default mode (COMPILE_MODE=compile-and-run) for users with hardware.
For specialized workflows like profiling with custom test executables:
make profile
What this does:
compile-and-xclbin mode to generate xclbin and instructionsThe sweep4x4 target similarly uses compile-and-xclbin to benchmark across multiple problem sizes with a custom test harness.
Different herd configurations:
make run2x2 COMPILE_MODE=compile-only # 2x2 herd
make run8x4 COMPILE_MODE=compile-only # 8x4 herd
Different architectures:
make run4x4 AIE_TARGET=aie2p COMPILE_MODE=compile-only # For NPU2/Strix
make run4x4 AIE_TARGET=aie2 # For NPU1/Phoenix (default)
View generated MLIR:
make print # Display MLIR module without compiling
Clean build artifacts:
make clean
The same patterns work for other matrix multiplication examples:
programming_examples/matrix_multiplication/bf16/ - bfloat16 matrix multiplyprogramming_examples/matrix_multiplication/i16/ - int16 matrix multiplyExplore programming_examples/ for many more examples including:
Most examples follow similar Makefile patterns with COMPILE_MODE and AIE_TARGET support.
The following instructions describe the manual, source-based build process. This is generally not required unless you need to build from source for development or debugging.
The MLIR-AIE repo maintains instructions on how to install dependencies and configure your environment. Follow the instructions here. It is not necessary to follow the final steps for cloning/building/running MLIR-AIE itself.
Building MLIR-AIR requires several other open source packages:
These prerequisites can be installed with some helpful scripts found in the utils directory in the process described below.
First, clone the MLIR-AIR repo:
git clone https://github.com/Xilinx/mlir-air.git
cd mlir-air
Next, run utils/setup_python_packages.sh to setup the prerequisite python packages. This script creates and installs the python packages listed in utils/requirements.txt in a virtual python environment called sandbox.
source utils/setup_python_packages.sh
Next, clone and build LLVM, with MLIR enabled. In addition, we make some common build optimizations to use a linker (‘lld’ or ‘gold’) other than ‘ld’ (which tends to be quite slow on large link jobs) and to link against libLLVM.so and libClang.so. You may find that other options are also useful. Note that due to changing MLIR APIs, only a particular revision is expected to work.
Run the following to clone and build llvm:
./utils/clone-llvm.sh
./utils/build-llvm-local.sh llvm
Next, clone and build the aienginev2 module. The installed files should be generated under aienginev2/install.
./utils/github-clone-build-libxaie.sh
Next, clone and build MLIR-AIE with paths to llvm, aienginev2, and cmakeModules repositories. MLIR-AIE requires some dependent packages to be installed. For details on the MLIR-AIE prerequisites, please refer to the MLIR-AIE repository. Once the prerequisites are set up, run the following commands to build MLIR-AIE.
./utils/clone-mlir-aie.sh
./utils/build-mlir-aie-local.sh llvm mlir-aie/cmake/modulesXilinx aienginev2/install mlir-aie
After this step, you are ready to build MLIR-AIR!
To build MLIR-AIR provide the paths to llvm, cmakeModules, and xrt (here, we assume it is installed in /opt/xilinx/xrt):
./utils/build-mlir-air-xrt.sh llvm mlir-aie/cmake/modulesXilinx mlir-aie aienginev2/install /opt/xilinx/xrt
To setup your environment after building:
# If you have llvm-aie (PEANO) installed via pip:
source utils/env_setup.sh install-xrt/ mlir-aie/install/ $(python3 -m pip show llvm-aie | grep Location | awk '{print $2}')/llvm-aie llvm/install/
# Or if you built llvm-aie from source:
source utils/env_setup.sh install-xrt/ mlir-aie/install/ /path/to/llvm-aie/install llvm/install/
Note that if you are starting a new environment (e.g., by creating a new terminal sometime after building), restore your environment with:
# If you have llvm-aie (PEANO) installed via pip:
source utils/env_setup.sh install-xrt/ mlir-aie/install/ $(python3 -m pip show llvm-aie | grep Location | awk '{print $2}')/llvm-aie llvm/install/
source sandbox/bin/activate
# Or if you built llvm-aie from source:
source utils/env_setup.sh install-xrt/ mlir-aie/install/ /path/to/llvm-aie/install llvm/install/
source sandbox/bin/activate
Some tests for MLIR-AIR are provided. Run them as demonstrated below:
cd mlir-air/build-xrt
ninja install
ninja check-air-cpp
ninja check-air-mlir
ninja check-air-python
# These are the ones in test/xrt, and this is about equivalent to `ninja check-air-e2e` if you set the LIT_OPS env var appropriately
lit -sv --time-tests --show-unsupported --show-excluded --timeout 600 -j5 test/xrt
# Run an individual test
lit -sv test/xrt/01_air_to_npu
# Run all xrt tests on device. Takes a long time.
ninja check-air-e2e
Copyright© 2022 Advanced Micro Devices, Inc.