mlir-aie
A close-to-metal Python API for programming AMD Ryzen™ AI NPUs (AI Engines), built on an open-source MLIR-based compiler toolchain.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 11 Nov 2026.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/Xilinx/mlir-aie with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/Xilinx/mlir-aie'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/xilinx--mlir-aie)HTML
<a href="/listings/xilinx--mlir-aie"><img src="/api/listings/xilinx--mlir-aie/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
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](docs/buildHostLinNonUbuntu.md). Please be aware that building for distributions other than Ubuntu is experimental. Support may vary.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 431 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- <!-- Copyright (C) 2019-2021 Xilinx, Inc. -->
- <!-- Copyright (C) 2022-2026 Advanced Micro Devices, Inc. -->
- <!-- SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception -->
- # IRON / MLIR-AIE
- **A close-to-metal Python API for programming AMD Ryzen™ AI NPUs, built on an open-source MLIR-based compiler toolchain.**
- [](https://github.com/Xilinx/mlir-aie/actions/workflows/buildAndTestPythons.yml)
- [](https://github.com/Xilinx/mlir-aie/tags)
- [](LICENSE)
- [](https://github.com/Xilinx/mlir-aie/graphs/contributors)
- [](https://discord.gg/UbXzGdXsR5)
- 📖 **[Documentation](https://xilinx.github.io/mlir-aie/)** · 🚀 **[Programming Guide](programming_guide/)** · 🐍 **[Python API](https://xilinx.github.io/mlir-aie/api/)** · 💡 **[Examples](programming_examples/)** · 📊 **[Dashboard](https://xilinx.github.io/mlir-aie/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](https://github.com/amd/RyzenAI-SW/) rather
- than replacing it.
- ```python
- 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](https://github.com/Xilinx/llvm-aie) compiler and runs it
- on the attached NPU. New to the concepts? Start with the
- [Programming Guide](programming_guide/) or the
- [Mini Tutorial](programming_guide/mini_tutorial/).
- <details markdown="1">
- <summary><b>More about the toolchain</b></summary>
- This repository contains an [MLIR-based](https://mlir.llvm.org/) toolchain for AI Engine-enabled devices, such as [AMD Ryzen™ AI](https://www.amd.com/en/products/processors/consumer/ryzen-ai.html) and [Versal™](https://www.xilinx.com/products/technology/ai-engine.html). 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](https://github.com/Xilinx/llvm-aie) 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](https://xilinx.github.io/aie_api/topics.html) 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](https://arxiv.org/abs/2504.18430)". In 33rd IEEE International Symposium On Field-Programmable Custom Computing Machines, May 2025.
- </details>
- ## Ryzen™ AI host setup
- | Host | Start here |
- | --- | --- |
- | Linux (Ubuntu) | [Continue with the Linux setup below](#getting-started-for-amd-ryzen-ai-on-linux) |
- | Linux (non-Ubuntu) | [Non-Ubuntu Linux Setup](docs/buildHostLinNonUbuntu.md) |
- | Windows 11 | [Native Windows Setup](docs/buildHostWinNative.md) |
- | Windows via WSL | [Windows via WSL Setup](docs/buildHostWin.md) |
- ## 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](docs/buildHostLinNonUbuntu.md). 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](#update-bios).
- - 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:
- ```bash
- uname -r
- ```
- If your kernel is older than 6.17, upgrade it using your distribution's kernel update mechanism -- on Ubuntu:
- ```bash
- 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`
- ```bash
- 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:
- >
- > ```bash
- > 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](#alternative-build-xdna-driver-and-xrt-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](docs/buildHostLinNonUbuntu.md).
- Verify the NPU device is present:
- ```bash
- 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:
- ```bash
- # 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:
- ```bash
- 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:**
- ````bash
- 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:
- ````bash
- 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):
- ```bash
- ./utils/build-mlir-aie-from-wheels.sh
- ```
- ### Manual Installation Steps
- Below steps replicate what the install script does.
- <details markdown="1">
- <summary>Manual installation steps</summary>
- 1. Setup a virtual environment:
- ```bash
- 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):
- ```bash
- # 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-5
- ```
- 1. **Latest Release:** Alternatively, you can install the latest released version of `mlir-aie`.
- ```bash
- # 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).
- ```bash
- # 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:
- ```bash
- # 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:
- ```bash
- # 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
- ```
- 1. Setup environment
- ```bash
- source utils/env_setup.sh
- ```
- 1. (Optional) Install ML Python packages for ml programming examples:
- ```bash
- # Install Torch for ML examples
- python3 -m pip install -r python/requirements_ml.txt
- ```
- 1. (Optional) Install Jupyter Notebook Python packages:
- ```bash
- # 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"
- ```
- </details>
- ## Run an IRON Design on the AMD Ryzen™ AI NPU on Linux
- The [programming examples](programming_examples/) use either of two entry points. Most examples use standalone `@iron.jit` to compile, run, and verify directly from Python:
- ```bash
- 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](programming_guide)
- 1. Additional MLIR-AIE documentation is available on the [website](https://xilinx.github.io/mlir-aie/)
- 1. AIE API header library documentation for single-core AIE programming in C++ is available [here](https://xilinx.github.io/aie_api/topics.html)
- 1. 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](https://www.amd.com/en/corporate/university-program/learning-cloud.html)
- 1. Have a question or want to talk with the team and other users? Join the [ROCm Discord](https://discord.gg/UbXzGdXsR5) 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](https://github.com/Xilinx/llvm-aie). 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](https://account.amd.com/en/member/ryzenai-sw-ea.html). 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`
- 1. Extract the required tools:
- ```bash
- 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
- ```
- 1. Set up an AI Engine license.
- 1. Get a local license for AI Engine tools from [https://www.xilinx.com/getlicense](https://www.xilinx.com/getlicense).
- 1. Copy your license file (Xilinx.lic) to your preferred location, e.g. `/opt/Xilinx.lic`:
- 1. Setup your environment using the following script for Vitis™ for AIETools:
- ```bash
- #!/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](#install-from-upstream-packages-ubuntu-2404-with-linux-617) 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
- bash ./utils/build_drivers.sh
- ```
- 1. Reboot as directed after the script exits.
- ```bash
- sudo reboot
- ```
- 1. Check that the NPU is working if the device appears with xrt-smi:
- ```bash
- 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](programming_guide)
- [Device Descriptions](docs/Devices.md)
- [AMD XDNA NPU Architecture Cheatsheet](skills/aie-iron-design/references/architecture.md) — 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](skills/aie-iron-design/references/kernel_intrinsics.md) — 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](skills/README.md) 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](skills/agentic_programming.md) for how the two fit together.
- [Building mlir-aie tools from source](docs/Building.md)
- [MLIR Dialect and Compiler Documentation](https://xilinx.github.io/mlir-aie/)
- Interested in contributing MLIR-AIE? [Information for developers](CONTRIBUTING.md)
- See our [Roadmap](ROADMAP.md) for where the project is headed, and our [Security Policy](SECURITY.md) for how to report vulnerabilities.
- -----
- <p align="center">Copyright© 2019-2021 Xilinx, Inc.<br>Copyright© 2022-2026 Advanced Micro Devices, Inc.</p>
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.