Installation (Linux)¶
These instructions take a fresh Ubuntu 24.04 or Ubuntu 24.10 install to building and running programs on the Ryzen™ AI NPU.
BIOS
Ensure your system has the latest BIOS version that enables NPU support. Check your laptop or mini-PC manufacturer's support website for BIOS updates.
1. Kernel, driver and XRT¶
On Ubuntu 24.04 you may need Linux 6.11 or later, from the Hardware Enablement (HWE) stack:
Then install the XDNA™ driver and XRT as mlir-aie's instructions describe.
2. The driver's command timeout¶
Give the driver a command timeout IRON's longest commands fit in. The amdxdna
driver ends a command after about two periods of its tdr_timeout_ms in which
no command on the device starts or finishes (2000 ms by default, so about
4 s), and the run reports ERT_CMD_STATE_TIMEOUT. IRON needs
tdr_timeout_ms=150000, so a command may run about 300 s. Set it, then
reload the driver or reboot:
echo "options amdxdna tdr_timeout_ms=150000" | sudo tee /etc/modprobe.d/amdxdna-tdr.conf
sudo modprobe -r amdxdna && sudo modprobe amdxdna
On NPU2 a model's prompt chunk is one command, and the deepest chunk, at the
model's native context, is the longest. The timeout must cover it, with room
to spare on a slower device. CI's nightly times a whole prompt at the native
context, which bounds its deepest chunk from above: long_context's TTFT on
the Performance Checks page.
On NPU1 a command is one operator, the longest an attention layer of the
deepest chunk.
3. System packages¶
IRON needs Python 3.11 to 3.14, the versions the mlir-aie wheels are built for:
4. IRON and its Python packages¶
Clone IRON, set up a virtual environment and source XRT:
git clone https://github.com/amd/IRON.git
cd IRON
python3 -m venv ironenv
source ironenv/bin/activate
python3 -m pip install --upgrade pip
source /opt/xilinx/xrt/setup.sh
Install the pinned packages. The mlir-aie wheel requirements.txt pins is a
nightly (AGENTS.md says how the pins move), and it
installs this checkout in editable mode:
Loading a model needs the models extra (huggingface_hub, tokenizers and
jinja2); the model tests also read images and audio:
pip install -e '.[models]' # to load and run models
pip install -r requirements_examples.txt # the extra and the model tests' packages
5. Check the installation¶
Build and run one operator on the NPU:
Next steps¶
- Run a model: Models.
- Write your own operators and graphs: the programming guide.
- The commands that run the operator and model tests: AGENTS.md.