Skip to content
Back to search

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.

Checked today

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/xilinx--mlir-aie/badge.svg)](/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

i

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.

  1. <!-- Copyright (C) 2019-2021 Xilinx, Inc. -->
  2. <!-- Copyright (C) 2022-2026 Advanced Micro Devices, Inc. -->
  3. <!-- SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception -->
  4. # IRON / MLIR-AIE
  5. **A close-to-metal Python API for programming AMD Ryzen™ AI NPUs, built on an open-source MLIR-based compiler toolchain.**
  6. [![Build](https://img.shields.io/github/actions/workflow/status/Xilinx/mlir-aie/buildAndTestPythons.yml?branch=main&label=build&cacheSeconds=86400)](https://github.com/Xilinx/mlir-aie/actions/workflows/buildAndTestPythons.yml)
  7. [![Latest tag](https://img.shields.io/github/v/tag/Xilinx/mlir-aie?sort=semver&label=release&cacheSeconds=86400)](https://github.com/Xilinx/mlir-aie/tags)
  8. [![License](https://img.shields.io/badge/license-Apache%202.0%20with%20LLVM%20exception-blue)](LICENSE)
  9. [![Contributors](https://img.shields.io/github/contributors/Xilinx/mlir-aie?cacheSeconds=86400)](https://github.com/Xilinx/mlir-aie/graphs/contributors)
  10. [![Discord](https://img.shields.io/badge/Discord-ROCm--NPU-5865F2?logo=discord&logoColor=white)](https://discord.gg/UbXzGdXsR5)
  11. 📖 **[Documentation](https://xilinx.github.io/mlir-aie/)** &nbsp;·&nbsp; 🚀 **[Programming Guide](programming_guide/)** &nbsp;·&nbsp; 🐍 **[Python API](https://xilinx.github.io/mlir-aie/api/)** &nbsp;·&nbsp; 💡 **[Examples](programming_examples/)** &nbsp;·&nbsp; 📊 **[Dashboard](https://xilinx.github.io/mlir-aie/dashboard/)**
  12. Write Python. Run it on the NPU. IRON compiles your Python design straight to
  13. the AI Engine array inside AMD Ryzen™ AI processors — you control tile
  14. placement, data movement, and vectorized compute, with nothing hidden behind a
  15. framework. Built for researchers and performance engineers pushing the NPU on
  16. everything from machine learning to digital signal processing, IRON
  17. *complements* mainstream inference tooling like the
  18. [AMD Ryzen™ AI Software Platform](https://github.com/amd/RyzenAI-SW/) rather
  19. than replacing it.
  20. ```python
  21. import aie.iron as iron
  22. from aie.iron import ObjectFifo, Program, Runtime, Worker
  23. from aie.iron.controlflow import range_
  24. import numpy as np
  25. data_ty = np.ndarray[(1024,), np.dtype[np.int32]]
  26. @iron.jit
  27. def vector_add_one(a_in, b_out):
  28. of_in = ObjectFifo(data_ty, name="in") # host → compute tile
  29. of_out = ObjectFifo(data_ty, name="out") # compute tile → host
  30. def core_fn(of_in, of_out): # runs on one AIE core
  31. a = of_in.acquire(1)
  32. b = of_out.acquire(1)
  33. for i in range_(1024):
  34. b[i] = a[i] + 1
  35. of_in.release(1); of_out.release(1)
  36. w = Worker(core_fn, [of_in.cons(), of_out.prod()])
  37. def sequence(a, b, in_h, out_h):
  38. in_h.fill(a)
  39. out_h.drain(b, wait=True)
  40. rt = Runtime(sequence, [data_ty, data_ty, of_in.prod(), of_out.cons()])
  41. return Program(iron.get_current_device(), rt, workers=[w]).resolve_program()
  42. a = iron.arange(1024, dtype=np.int32, device="npu")
  43. b = iron.zeros(1024, dtype=np.int32, device="npu")
  44. vector_add_one(a, b) # JIT-compiles on first call, runs on the NPU, caches after
  45. ```
  46. `@iron.jit` compiles the design to an `xclbin` + instruction stream via the
  47. LLVM/MLIR-based [Peano](https://github.com/Xilinx/llvm-aie) compiler and runs it
  48. on the attached NPU. New to the concepts? Start with the
  49. [Programming Guide](programming_guide/) or the
  50. [Mini Tutorial](programming_guide/mini_tutorial/).
  51. <details markdown="1">
  52. <summary><b>More about the toolchain</b></summary>
  53. 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.
  54. 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.
  55. IRON is described in the following paper:
  56. > 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.
  57. </details>
  58. ## Ryzen™ AI host setup
  59. | Host | Start here |
  60. | --- | --- |
  61. | Linux (Ubuntu) | [Continue with the Linux setup below](#getting-started-for-amd-ryzen-ai-on-linux) |
  62. | Linux (non-Ubuntu) | [Non-Ubuntu Linux Setup](docs/buildHostLinNonUbuntu.md) |
  63. | Windows 11 | [Native Windows Setup](docs/buildHostWinNative.md) |
  64. | Windows via WSL | [Windows via WSL Setup](docs/buildHostWin.md) |
  65. ## Getting Started for AMD Ryzen™ AI on Linux
  66. 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.
  67. > **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.
  68. ## Prerequisites
  69. ### BIOS Settings
  70. - Be sure you have the latest BIOS on your laptop or mini-PC that enables the NPU. See [here](#update-bios).
  71. - Turn off SecureBoot (Allows for unsigned drivers to be installed):
  72. `BIOS → Security → Secure boot → Disable`
  73. ### Linux Kernel
  74. Ensure your system is running Linux kernel **6.17 or newer** before installing these packages. On Ubuntu 24.04 you can verify this with:
  75. ```bash
  76. uname -r
  77. ```
  78. If your kernel is older than 6.17, upgrade it using your distribution's kernel update mechanism -- on Ubuntu:
  79. ```bash
  80. sudo apt update
  81. sudo apt install --install-recommends linux-generic-hwe-24.04
  82. sudo reboot
  83. ```
  84. ### Install the XDNA™ Driver and XRT
  85. #### Install from upstream packages (Ubuntu 24.04 with Linux 6.17+)
  86. Install the XDNA driver and XRT from the AMD PPA:
  87. > The packaged XRT only supports Python 3.12 for `pyxrt`
  88. ```bash
  89. sudo add-apt-repository ppa:amd-team/xrt
  90. sudo apt update
  91. sudo apt install libxrt2 libxrt-npu2 libxrt-dev libxrt-utils libxrt-utils-npu amdxdna-dkms
  92. sudo reboot
  93. ```
  94. > Make sure you are in the `render` group to access the NPU:
  95. >
  96. > ```bash
  97. > sudo usermod -aG render $USER
  98. > ```
  99. >
  100. > You may need to logout and log back in after modifying user groups.
  101. > 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).
  102. Verify the NPU device is present:
  103. ```bash
  104. xrt-smi examine
  105. ```
  106. > At the bottom of the output you should see:
  107. > ```
  108. > Devices present
  109. > BDF : Name
  110. > ------------------------------------
  111. > [0000:66:00.1] : NPU Strix
  112. > ```
  113. ### Install IRON and MLIR-AIE Prerequisites
  114. Install the following packages needed for MLIR-AIE:
  115. ```bash
  116. # Python versions 3.11, 3.12, 3.13, and 3.14 are currently supported by our wheels
  117. sudo apt install \
  118. build-essential clang clang-14 lld lld-14 cmake ninja-build python3-venv python3-pip uuid-dev
  119. ```
  120. (Optional) Install opencv which is needed for vision programming examples:
  121. ```bash
  122. sudo apt install libopencv-dev python3-opencv
  123. ```
  124. ## Install IRON for AMD Ryzen™ AI AIE Application Development
  125. ### From Pre-Built Binaries (Wheels)
  126. Set up and source a Python virtual environment and install the IRON library
  127. (`mlir-aie` wheel), and per-core compiler ("peano", `llvm-aie` wheel). The
  128. following is the **quickest path:**
  129. ````bash
  130. source utils/env_install.sh # one time / first time
  131. source utils/env_setup.sh # every time you open a new shell
  132. ````
  133. This creates an environment named `ironenv` containing the toolchain.
  134. By default, the script will match the `mlir_aie` wheel associated with the
  135. currently checked-out release/commit of the repository. If it can't find a
  136. release for this commit, it will error, since trying to compile a version of
  137. the programming examples in this repository with a compiler wheel whose version
  138. does not exactly match very frequently leads to hard-to-debug errors. If you
  139. insist on using the latest available release from `main`, pass `--latest`. To
  140. manually install a different wheel, follow the manual instructions below.
  141. > *Tip:* The `utils/env_install.sh` script also works as an update script.
  142. ### From Source
  143. To build the compiler toolchain from source, you'll need additional
  144. dependencies. Install the requirements using:
  145. ````bash
  146. source utils/env_install.sh --dev # one time / first time
  147. source utils/env_setup.sh # every time you open a new shell
  148. ````
  149. Then, build the compiler (`_from_wheels.sh` in this case refers to the LLVM
  150. installation being pulled from a wheel; MLIR-AIE links against LLVM, but will
  151. be built from source):
  152. ```bash
  153. ./utils/build-mlir-aie-from-wheels.sh
  154. ```
  155. ### Manual Installation Steps
  156. Below steps replicate what the install script does.
  157. <details markdown="1">
  158. <summary>Manual installation steps</summary>
  159. 1. Setup a virtual environment:
  160. ```bash
  161. python3 -m venv ironenv
  162. source ironenv/bin/activate
  163. python3 -m pip install --upgrade pip
  164. ```
  165. 1. Install IRON library by installing the `mlir-aie` wheels:
  166. For installing the `mlir-aie` wheels, there are 3 options. Note that for whichever path you take, it is
  167. important to sync the `mlir-aie` wheels version, the GitHub repo commit, and the requirements versions. If
  168. you install from something other than the latest wheels, make sure you use the repo commit -- and
  169. installation instructions -- from that point in time.
  170. 1. **Latest:** For the latest wheels (not necessarily a release):
  171. ```bash
  172. # Install IRON library and mlir-aie from the latest wheel
  173. python3 -m pip install mlir_aie -f https://github.com/Xilinx/mlir-aie/releases/expanded_assets/latest-wheels-5
  174. ```
  175. 1. **Latest Release:** Alternatively, you can install the latest released version of `mlir-aie`.
  176. ```bash
  177. # Get the latest release version
  178. latest_tag_with_v=$(curl -s "https://api.github.com/repos/Xilinx/mlir-aie/releases/latest" | jq -r '.tag_name')
  179. latest_tag="${latest_tag_with_v#v}"
  180. # Install IRON library and mlir-aie from the latest stable release
  181. python3 -m pip install mlir_aie==${latest_tag} -f https://github.com/Xilinx/mlir-aie/releases/expanded_assets/${latest_tag_with_v}
  182. git checkout $latest_tag_with_v
  183. ```
  184. 1. **Any Release:** You can install a specific version of `mlir-aie` from the release wheels. To see
  185. available versions, check out the [release page](https://github.com/Xilinx/mlir-aie/releases).
  186. ```bash
  187. # Install IRON library and mlir-aie from a specific release,
  188. # e.g., <version> in the following command could be replaced with v1.1.3
  189. python3 -m pip install mlir_aie -f https://github.com/Xilinx/mlir-aie/releases/expanded_assets/<version>
  190. git checkout <version>
  191. ```
  192. 1. Install the Peano compiler (the `llvm-aie` wheels) and dependencies:
  193. ```bash
  194. # Install Peano from the llvm-aie wheel, pinned to the tested nightly in
  195. # utils/peano-requirements.txt (the same pin CI uses; bumped by the update-peano
  196. # workflow). To grab the latest nightly instead, install `llvm-aie` directly
  197. # with `-f https://github.com/Xilinx/llvm-aie/releases/expanded_assets/nightly`.
  198. python3 -m pip install -r utils/peano-requirements.txt
  199. ```
  200. 1. (Optional) Install Python packages required for development and testing:
  201. ```bash
  202. # Install Python requirements for development and testing
  203. python3 -m pip install -r python/requirements_dev.txt
  204. # Install the pre-commit and pre-push hooks defined in .pre-commit-config.yaml
  205. # (pre-push runs clang-format/black/ruff to catch formatting and lint issues before CI)
  206. pre-commit install
  207. ```
  208. 1. Setup environment
  209. ```bash
  210. source utils/env_setup.sh
  211. ```
  212. 1. (Optional) Install ML Python packages for ml programming examples:
  213. ```bash
  214. # Install Torch for ML examples
  215. python3 -m pip install -r python/requirements_ml.txt
  216. ```
  217. 1. (Optional) Install Jupyter Notebook Python packages:
  218. ```bash
  219. # Install Jupyter Notebook
  220. python3 -m pip install -r python/requirements_notebook.txt
  221. # This creates an ipykernel (for use in notebooks) using the ironenv venv
  222. python3 -m ipykernel install --user --name ironenv
  223. # Only for Release v1.0 and non wheel-based installs:
  224. # The install generally captures in the $PYTHONPATH by the `env_setup.sh` script.
  225. # However, jupyter notebooks don't always get access to the PYTHONPATH (e.g., if they are run with
  226. # vscode) so we save the ${MLIR_AIE_INSTALL_DIR}/python in a .pth file in the site packages dir of the
  227. # ironenv venv; this allows the iron ipykernel to find the install dir regardless of if PYTHONPATH is
  228. # available or not.
  229. MLIR_AIE_INSTALL="$(pip show mlir_aie | grep ^Location: | awk '{print $2}')/mlir_aie"
  230. venv_site_packages="$(python3 -c 'import sysconfig; print(sysconfig.get_paths()["purelib"])')"
  231. echo "${MLIR_AIE_INSTALL}/python" > "$venv_site_packages/mlir-aie.pth"
  232. ```
  233. </details>
  234. ## Run an IRON Design on the AMD Ryzen™ AI NPU on Linux
  235. 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:
  236. ```bash
  237. cd programming_examples/<category>/<example>
  238. python3 <example>.py
  239. ```
  240. 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`.
  241. ## Learn more about NPU programming with IRON
  242. 1. Continue to the [IRON AIE Application Programming Guide](programming_guide)
  243. 1. Additional MLIR-AIE documentation is available on the [website](https://xilinx.github.io/mlir-aie/)
  244. 1. AIE API header library documentation for single-core AIE programming in C++ is available [here](https://xilinx.github.io/aie_api/topics.html)
  245. 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)
  246. 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
  247. ## Optional: Install AIETools
  248. > 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.
  249. 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`.
  250. > This is an early access lounge, you must register and be granted access at this time.
  251. 1. Download VAIML Installer for Linux based compilation: `ryzen_ai-1.3.0ea1.tgz`
  252. 1. Extract the required tools:
  253. ```bash
  254. tar -xzvf ryzen_ai-1.3.0ea1.tgz
  255. cd ryzen_ai-1.3.0
  256. mkdir vitis_aie_essentials
  257. mv vitis_aie_essentials*.whl vitis_aie_essentials
  258. cd vitis_aie_essentials
  259. unzip vitis_aie_essentials*.whl
  260. ```
  261. 1. Set up an AI Engine license.
  262. 1. Get a local license for AI Engine tools from [https://www.xilinx.com/getlicense](https://www.xilinx.com/getlicense).
  263. 1. Copy your license file (Xilinx.lic) to your preferred location, e.g. `/opt/Xilinx.lic`:
  264. 1. Setup your environment using the following script for Vitis™ for AIETools:
  265. ```bash
  266. #!/bin/bash
  267. #################################################################################
  268. # Setup Vitis AIE Essentials
  269. #################################################################################
  270. export AIETOOLS_ROOT=/tools/ryzen_ai-1.3.0/vitis_aie_essentials
  271. export PATH=$PATH:${AIETOOLS_ROOT}/bin
  272. export LM_LICENSE_FILE=/opt/Xilinx.lic
  273. ```
  274. ## Alternative: Build XDNA™ Driver and XRT from source
  275. 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:
  276. 1. Execute the scripted build process:
  277. > This script will install package dependencies, build the xdna-driver and xrt packages, and install them. *These steps require `sudo` access.*
  278. ```bash
  279. bash ./utils/build_drivers.sh
  280. ```
  281. 1. Reboot as directed after the script exits.
  282. ```bash
  283. sudo reboot
  284. ```
  285. 1. Check that the NPU is working if the device appears with xrt-smi:
  286. ```bash
  287. source /opt/xilinx/xrt/setup.sh
  288. xrt-smi examine
  289. ```
  290. ## Troubleshooting
  291. ### Update BIOS
  292. 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:
  293. `Advanced → CPU Configuration → IPU`
  294. > **NOTE:** Some manufacturers only provide Windows executables to update the BIOS, please do this before installing Ubuntu.
  295. # Detailed Getting Started Guides and Documentation
  296. [IRON AIE Application Programming Guide](programming_guide)
  297. [Device Descriptions](docs/Devices.md)
  298. [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
  299. [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
  300. 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.
  301. [Building mlir-aie tools from source](docs/Building.md)
  302. [MLIR Dialect and Compiler Documentation](https://xilinx.github.io/mlir-aie/)
  303. Interested in contributing MLIR-AIE? [Information for developers](CONTRIBUTING.md)
  304. See our [Roadmap](ROADMAP.md) for where the project is headed, and our [Security Policy](SECURITY.md) for how to report vulnerabilities.
  305. -----
  306. <p align="center">Copyright&copy; 2019-2021 Xilinx, Inc.<br>Copyright&copy; 2022-2026 Advanced Micro Devices, Inc.</p>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.