Getting Started¶

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

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)

    rt = Runtime()
    with rt.sequence(data_ty, data_ty) as (a, b):
        rt.start(Worker(core_fn, [of_in.cons(), of_out.prod()]))
        rt.fill(of_in.prod(), a)
        rt.drain(of_out.cons(), b, wait=True)
    return Program(iron.get_current_device(), rt).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.

More about the toolchain

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.

Initial Setup¶

Be sure you have the latest BIOS on your laptop or mini-PC that enables the NPU. See here.

If starting from Ubuntu 24.04 you may need to update the Linux kernel to 6.11+ by installing the Hardware Enablement (HWE) stack:

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

Prerequisites¶

BIOS Settings:¶

Turn off SecureBoot (Allows for unsigned drivers to be installed): BIOS → Security → Secure boot → Disable

Install the XDNA™ Driver and XRT¶

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

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 or the kernel upgrade steps described in the Initial Setup section above.

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
```
Note: CMake 3.30 or newer is required. If your distribution provides an older version, create and activate the Python virtual environment in the setup step below first, then install a newer CMake into that virtual environment:
```
python3 -m pip install --upgrade cmake
```
(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¶

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

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 and installs the mlir_aie and Peano wheels. For a from-source build use source utils/env_install.sh --dev. 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.

Below are the manual installation steps if you prefer to do this yourself.

Manual installation steps

1. Setup a virtual environment:

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

1. 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

1. **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

1. **Any Release:** You can install a specific version of `mlir-aie` from the release wheels. To see available versions, check out the [release page](https://github.com/Xilinx/mlir-aie/releases).

# 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>

1. 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

1. (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 to catch formatting issues before CI)
pre-commit install

1. Setup environment

source utils/env_setup.sh

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

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

1. (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"

Build an IRON Design for AIEs in the AMD Ryzen™ AI NPU on Linux¶

For your design of interest, for instance from programming_examples, 2 steps are needed: (i) build the AIE design and then (ii) build the host code.

Build Device AIE Part¶

Go to the design of interest and run:
```
make
```
Build host code and execute the design:
```
make run
```

Learn more about NPU programming with IRON¶

Continue to the IRON AIE Application Programming Guide
Additional MLIR-AIE documentation is available on the website
AIE API header library documentation for single-core AIE programming in C++ is available here
If you are a university researcher or student and interested in trying these tools on our Ryzen™ AI AUP Cloud systems, please contact the AMD University Program

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.

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.

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

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

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:
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:

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
```
Reboot as directed after the script exits.
```
sudo reboot
```
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

Building mlir-aie tools from source

MLIR Dialect and Compiler Documentation

Interested in contributing MLIR-AIE? Information for developers