mlir-aie

IRON / MLIR-AIE

A close-to-metal Python API for programming AMD Ryzen™ AI NPUs, built on an open-source MLIR-based compiler toolchain.

📖 Documentation  ·  🚀 Programming Guide  ·  🐍 Python API  ·  💡 Examples  ·  📊 Dashboard

Write Python. Run it on the NPU. IRON compiles your Python design straight to the AI Engine array inside AMD Ryzen™ AI processors — you control tile placement, data movement, and vectorized compute, with nothing hidden behind a framework. Built for researchers and performance engineers pushing the NPU on everything from machine learning to digital signal processing, IRON complements mainstream inference tooling like the AMD Ryzen™ AI Software Platform rather than replacing it.

import aie.iron as iron
from aie.iron import ObjectFifo, Program, Runtime, Worker
from aie.iron.controlflow import range_
import numpy as np

data_ty = np.ndarray[(1024,), np.dtype[np.int32]]

@iron.jit
def vector_add_one(a_in, b_out):
    of_in  = ObjectFifo(data_ty, name="in")     # host → compute tile
    of_out = ObjectFifo(data_ty, name="out")    # compute tile → host

    def core_fn(of_in, of_out):                 # runs on one AIE core
        a = of_in.acquire(1)
        b = of_out.acquire(1)
        for i in range_(1024):
            b[i] = a[i] + 1
        of_in.release(1); of_out.release(1)

    w = Worker(core_fn, [of_in.cons(), of_out.prod()])

    def sequence(a, b, in_h, out_h):
        in_h.fill(a)
        out_h.drain(b, wait=True)

    rt = Runtime(sequence, [data_ty, data_ty, of_in.prod(), of_out.cons()])
    return Program(iron.get_current_device(), rt, workers=[w]).resolve_program()

a = iron.arange(1024, dtype=np.int32, device="npu")
b = iron.zeros(1024,  dtype=np.int32, device="npu")
vector_add_one(a, b)   # JIT-compiles on first call, runs on the NPU, caches after

@iron.jit compiles the design to an xclbin + instruction stream via the LLVM/MLIR-based Peano compiler and runs it on the attached NPU. New to the concepts? Start with the Programming Guide or the Mini Tutorial.

This repository contains an MLIR-based toolchain for AI Engine-enabled devices, such as AMD Ryzen™ AI and Versal™. It generates low-level configurations for the AI Engine portion of these devices. AI Engines are organized as a spatial array of tiles, where each tile contains AI Engine cores and/or memories. The spatial array is connected by stream switches that route data between tiles, scheduled by their programmable Data Movement Accelerators (DMAs). The repository provides MLIR representations at multiple levels of abstraction to target AI Engine devices, enabling compilers and developers to program cores and describe data movement and array connectivity.

The Peano component extends LLVM with the AI Engine processor as a target architecture, enabling integration with compiler frontends such as clang. Developers can use the AIE API header library to write efficient vectorized AIE core code in C++ that Peano compiles.

IRON is described in the following paper:

E. Hunhoff, J. Melber, K. Denolf, A. Bisca, S. Bayliss, S. Neuendorffer, J. Fifield, J. Lo, P. Vasireddy, P. James-Roxby, E. Keller. "Efficiency, Expressivity, and Extensibility in a Close-to-Metal NPU Programming Interface". In 33rd IEEE International Symposium On Field-Programmable Custom Computing Machines, May 2025.

Ryzen™ AI host setup

Host	Start here
Linux (Ubuntu)	Continue with the Linux setup below
Linux (non-Ubuntu)	Non-Ubuntu Linux Setup
Windows 11	Native Windows Setup
Windows via WSL	Windows via WSL Setup

Getting Started for AMD Ryzen™ AI on Linux

These instructions will guide you through everything required for building and executing a program on the Ryzen™ AI NPU, starting from a fresh bare-bones Ubuntu 24.04 or Ubuntu 24.10 install.

NOTE: If you are using a different Linux distribution, see the non-Ubuntu build guide. Please be aware that building for distributions other than Ubuntu is experimental. Support may vary.

Prerequisites

BIOS Settings

• Be sure you have the latest BIOS on your laptop or mini-PC that enables the NPU. See here.
• Turn off SecureBoot (Allows for unsigned drivers to be installed): BIOS → Security → Secure boot → Disable

Linux Kernel

Ensure your system is running Linux kernel 6.17 or newer before installing these packages. On Ubuntu 24.04 you can verify this with:

uname -r

If your kernel is older than 6.17, upgrade it using your distribution's kernel update mechanism -- on Ubuntu:

sudo apt update
sudo apt install --install-recommends linux-generic-hwe-24.04
sudo reboot

Install the XDNA™ Driver and XRT

Install from upstream packages (Ubuntu 24.04 with Linux 6.17+)

Install the XDNA driver and XRT from the AMD PPA:

The packaged XRT only supports Python 3.12 for pyxrt

sudo add-apt-repository ppa:amd-team/xrt
sudo apt update
sudo apt install libxrt2 libxrt-npu2 libxrt-dev libxrt-utils libxrt-utils-npu amdxdna-dkms
sudo reboot

Make sure you are in the render group to access the NPU:

sudo usermod -aG render $USER

You may need to logout and log back in after modifying user groups.

If you are on a different Linux distribution or kernel not supported by the upstream packages, see Build from source below. For non-Ubuntu distros (Arch, Void, Fedora-from-source, …) or kernels that already ship the in-tree amdxdna driver (Linux ≥ 6.14), see the non-Ubuntu build guide.

Verify the NPU device is present:

xrt-smi examine

At the bottom of the output you should see:

Devices present
BDF             :  Name
------------------------------------
[0000:66:00.1]  :  NPU Strix

Install IRON and MLIR-AIE Prerequisites

Install the following packages needed for MLIR-AIE:

# Python versions 3.11, 3.12, 3.13, and 3.14 are currently supported by our wheels
sudo apt install \
build-essential clang clang-14 lld lld-14 cmake ninja-build python3-venv python3-pip uuid-dev

(Optional) Install opencv which is needed for vision programming examples:

sudo apt install libopencv-dev python3-opencv

Install IRON for AMD Ryzen™ AI AIE Application Development

From Pre-Built Binaries (Wheels)

Set up and source a Python virtual environment and install the IRON library (mlir-aie wheel), and per-core compiler ("peano", llvm-aie wheel). The following is the quickest path:

source utils/env_install.sh  # one time / first time
source utils/env_setup.sh    # every time you open a new shell

This creates an environment named ironenv containing the toolchain.

By default, the script will match the mlir_aie wheel associated with the currently checked-out release/commit of the repository. If it can't find a release for this commit, it will error, since trying to compile a version of the programming examples in this repository with a compiler wheel whose version does not exactly match very frequently leads to hard-to-debug errors. If you insist on using the latest available release from main, pass --latest. To manually install a different wheel, follow the manual instructions below.

Tip: The utils/env_install.sh script also works as an update script.

From Source

To build the compiler toolchain from source, you'll need additional dependencies. Install the requirements using:

source utils/env_install.sh --dev  # one time / first time
source utils/env_setup.sh    # every time you open a new shell

Then, build the compiler (_from_wheels.sh in this case refers to the LLVM installation being pulled from a wheel; MLIR-AIE links against LLVM, but will be built from source):

./utils/build-mlir-aie-from-wheels.sh

Manual Installation Steps

Below steps replicate what the install script does.

1. Setup a virtual environment:

   python3 -m venv ironenv
   source ironenv/bin/activate
   python3 -m pip install --upgrade pip
   

2. Install IRON library by installing the mlir-aie wheels:

   For installing the mlir-aie wheels, there are 3 options. Note that for whichever path you take, it is important to sync the mlir-aie wheels version, the GitHub repo commit, and the requirements versions. If you install from something other than the latest wheels, make sure you use the repo commit -- and installation instructions -- from that point in time.

   1. Latest: For the latest wheels (not necessarily a release):

      # Install IRON library and mlir-aie from the latest wheel
      python3 -m pip install mlir_aie -f https://github.com/Xilinx/mlir-aie/releases/expanded_assets/latest-wheels-4
      

   2. Latest Release: Alternatively, you can install the latest released version of mlir-aie.

      # Get the latest release version
      latest_tag_with_v=$(curl -s "https://api.github.com/repos/Xilinx/mlir-aie/releases/latest" | jq -r '.tag_name')
      latest_tag="${latest_tag_with_v#v}"
      
      # Install IRON library and mlir-aie from the latest stable release
      python3 -m pip install mlir_aie==${latest_tag} -f https://github.com/Xilinx/mlir-aie/releases/expanded_assets/${latest_tag_with_v}
      git checkout $latest_tag_with_v
      

   3. Any Release: You can install a specific version of mlir-aie from the release wheels. To see available versions, check out the release page.

      # Install IRON library and mlir-aie from a specific release,
      # e.g., <version> in the following command could be replaced with v1.1.3
      python3 -m pip install mlir_aie -f https://github.com/Xilinx/mlir-aie/releases/expanded_assets/<version>
      git checkout <version>
      

3. Install the Peano compiler (the llvm-aie wheels) and dependencies:

   # Install Peano from the llvm-aie wheel, pinned to the tested nightly in
   # utils/peano-requirements.txt (the same pin CI uses; bumped by the update-peano
   # workflow). To grab the latest nightly instead, install `llvm-aie` directly
   # with `-f https://github.com/Xilinx/llvm-aie/releases/expanded_assets/nightly`.
   python3 -m pip install -r utils/peano-requirements.txt
   

4. (Optional) Install Python packages required for development and testing:

   # Install Python requirements for development and testing
   python3 -m pip install -r python/requirements_dev.txt
   
   # Install the pre-commit and pre-push hooks defined in .pre-commit-config.yaml
   # (pre-push runs clang-format/black/ruff to catch formatting and lint issues before CI)
   pre-commit install
   

5. Setup environment

   source utils/env_setup.sh
   

6. (Optional) Install ML Python packages for ml programming examples:

   # Install Torch for ML examples
   python3 -m pip install -r python/requirements_ml.txt
   

7. (Optional) Install Jupyter Notebook Python packages:

   # Install Jupyter Notebook
   python3 -m pip install -r python/requirements_notebook.txt
   
   # This creates an ipykernel (for use in notebooks) using the ironenv venv
   python3 -m ipykernel install --user --name ironenv
   
   # Only for Release v1.0 and non wheel-based installs:
   # The install generally captures in the $PYTHONPATH by the `env_setup.sh` script.
   # However, jupyter notebooks don't always get access to the PYTHONPATH (e.g., if they are run with
   # vscode) so we save the ${MLIR_AIE_INSTALL_DIR}/python in a .pth file in the site packages dir of the
   # ironenv venv; this allows the iron ipykernel to find the install dir regardless of if PYTHONPATH is
   # available or not.
   MLIR_AIE_INSTALL="$(pip show mlir_aie | grep ^Location: | awk '{print $2}')/mlir_aie"
   venv_site_packages="$(python3 -c 'import sysconfig; print(sysconfig.get_paths()["purelib"])')"
   echo "${MLIR_AIE_INSTALL}/python" > "$venv_site_packages/mlir-aie.pth"
   

Run an IRON Design on the AMD Ryzen™ AI NPU on Linux

The programming examples use either of two entry points. Most examples use standalone @iron.jit to compile, run, and verify directly from Python:

cd programming_examples/<category>/<example>
python3 <example>.py

Examples with a separate native host, explicit artifact builds, or multi-stage workflow have a Makefile. Follow the example's README for its supported targets, such as make run or make run_py.

Learn more about NPU programming with IRON

1. Continue to the IRON AIE Application Programming Guide

2. Additional MLIR-AIE documentation is available on the website

3. AIE API header library documentation for single-core AIE programming in C++ is available here

4. If you are a university researcher or student and interested in trying these tools on our Ryzen™ AI AUP Cloud systems, please visit the AMD University Program

5. Have a question or want to talk with the team and other users? Join the ROCm Discord and look for the ROCm-NPU channel

Optional: Install AIETools

You may skip the Vitis™ installation step if you intend to only target AMD XDNA™/AIE-ML (AIE2) and AMD XDNA™ 2 (AIE2P) using our open-source single-core compiler Peano. Compiling with xchesscc is not supported without installing AMD Vitis™ AIE Essentials.

1. Install Vitis™ AIE Essentials from Ryzen AI Software 1.3 Early Access. We will assume you use the installation directory, /tools/ryzen_ai-1.3.0/vitis_aie_essentials.

   This is an early access lounge, you must register and be granted access at this time.

   1. Download VAIML Installer for Linux based compilation: ryzen_ai-1.3.0ea1.tgz

   2. Extract the required tools:

      tar -xzvf ryzen_ai-1.3.0ea1.tgz
      cd ryzen_ai-1.3.0
      mkdir vitis_aie_essentials
      mv vitis_aie_essentials*.whl vitis_aie_essentials
      cd vitis_aie_essentials
      unzip vitis_aie_essentials*.whl
      

2. Set up an AI Engine license.

   1. Get a local license for AI Engine tools from https://www.xilinx.com/getlicense.

   2. Copy your license file (Xilinx.lic) to your preferred location, e.g. /opt/Xilinx.lic:

3. Setup your environment using the following script for Vitis™ for AIETools:

   #!/bin/bash
   #################################################################################
   # Setup Vitis AIE Essentials
   #################################################################################
   export AIETOOLS_ROOT=/tools/ryzen_ai-1.3.0/vitis_aie_essentials
   export PATH=$PATH:${AIETOOLS_ROOT}/bin
   export LM_LICENSE_FILE=/opt/Xilinx.lic
   

Alternative: Build XDNA™ Driver and XRT from source

If the upstream packages do not support your kernel or distribution, you can build the driver and XRT from source:

1. Execute the scripted build process:

   This script will install package dependencies, build the xdna-driver and xrt packages, and install them. These steps require sudo access.

   bash ./utils/build_drivers.sh
   

2. Reboot as directed after the script exits.

   sudo reboot
   

3. Check that the NPU is working if the device appears with xrt-smi:

   source /opt/xilinx/xrt/setup.sh
   xrt-smi examine
   

Troubleshooting

Update BIOS

Be sure you have the latest BIOS for your laptop or mini PC, this will ensure the NPU (sometimes referred to as IPU) is enabled in the system. You may need to manually enable the NPU: Advanced → CPU Configuration → IPU

NOTE: Some manufacturers only provide Windows executables to update the BIOS, please do this before installing Ubuntu.

Detailed Getting Started Guides and Documentation

IRON AIE Application Programming Guide

Device Descriptions

AMD XDNA NPU Architecture Cheatsheet — device/tile layout, memory hierarchy, vector register widths, MMUL shapes and divisibility constraints, routing/placement limits, and per-tile performance ballparks

AIE C++ Kernel Intrinsics Cheatsheet — AIE API boilerplate, loop-pipelining annotations, vector load/store, MMUL usage, and common intrinsic quick-reference tables

Working with a coding agent instead? The Agent Skills in this repo teach an agent (e.g. Claude Code) to write and optimize IRON designs the same way the Programming Guide teaches a person — see Agentic Programming for how the two fit together.

Building mlir-aie tools from source

MLIR Dialect and Compiler Documentation

Interested in contributing MLIR-AIE? Information for developers

See our Roadmap for where the project is headed, and our Security Policy for how to report vulnerabilities.

---