AMD NPU Driver and XRT Tools Installation Guide for Ubuntu 25.04

AMD_NPU_INSTALL_UBUNTU_25.04.md

AMD NPU Setup Guide for Ubuntu 25.04

Quick installation guide for enabling AMD Ryzen AI NPU on Ubuntu 25.04 with Secure Boot.

System Requirements

• Processor: AMD Ryzen AI processor (Strix/Phoenix series)
• OS: Ubuntu 25.04
• Kernel: 6.14+ (included in Ubuntu 25.04)
• Secure Boot: Can remain enabled (requires MOK enrollment)

Installation Steps

1. Clone Repository and Initialize Submodules

git clone https://github.com/amd/xdna-driver.git
cd xdna-driver
git submodule update --init --recursive

2. Install Build Dependencies

sudo ./tools/amdxdna_deps.sh

This installs required packages: cmake, gcc, boost, OpenCL headers, protobuf, and more.

3. Build XRT Base Package

cd xrt/build
./build.sh -npu -opt

# Install the generated package (adjust version as needed)
sudo apt reinstall ./Release/xrt_202610.2.21.0_25.04-amd64-base.deb

cd ../../

4. Build XRT Plugin (SHIM Library)

cd build
./build.sh -release

This creates xrt_plugin.2.21.0_25.04-amd64-amdxdna.deb in build/Release/.

5. Handle Secure Boot (MOK Enrollment)

If Secure Boot is enabled, you must enroll the MOK key before installing the plugin:

# Import MOK key (you'll be prompted to set a password)
sudo mokutil --import /var/lib/shim-signed/mok/MOK.der

# Reboot to complete enrollment
sudo reboot

During reboot:

1. MOK Manager (blue screen) will appear before GRUB
2. Select "Enroll MOK" → "Continue" → "Yes"
3. Enter the password you set
4. Select "Reboot"

Alternative: Disable Secure Boot in BIOS if you don't want to enroll MOK.

6. Install XRT Plugin

sudo apt install ./build/Release/xrt_plugin.2.21.0_25.04-amd64-amdxdna.deb

The DKMS module should load successfully after MOK enrollment.

7. Verify Installation

# Load XRT environment
source /opt/xilinx/xrt/setup.sh

# Check device detection
xrt-smi examine

# Run validation tests
xrt-smi validate --device <BDF>

Expected output:

• Device detected: NPU Strix at [0000:c2:00.1] (BDF may vary)
• All validation tests should pass (GEMM, latency, throughput)

Verification Commands

# Check driver is loaded
lsmod | grep amdxdna

# Check device node exists
ls -l /dev/accel/accel0

# Check MOK enrollment (if using Secure Boot)
mokutil --list-enrolled | grep "mod Secure Boot"

Troubleshooting

"Key was rejected by service" error

• MOK key not enrolled properly
• Solution: Re-run sudo mokutil --import and reboot
• Or disable Secure Boot in BIOS

XRT doesn't detect NPU

• Check driver is loaded: lsmod | grep amdxdna
• Check device exists: ls /dev/accel/accel0
• Verify you're in render group: groups
• Add user to render group if needed: sudo usermod -aG render $USER

Validation tests fail

• Ensure DKMS driver is loaded (not built-in): modinfo amdxdna | grep updates/dkms
• Check firmware version matches: xrt-smi examine should show 255.x.x.x
• Try removing and reinstalling xrt_plugin package

Performance Expectations

With successful installation, you should see:

• GEMM test: 50+ TOPS
• Latency: <50 microseconds average
• Throughput: 80,000+ ops/sec

Notes

• Ubuntu 25.04 includes amdxdna driver in kernel 6.14, but the DKMS version from this repo provides full functionality
• Firmware is included in the xrt_plugin package
• XRT environment must be sourced in each new shell session
• Add source /opt/xilinx/xrt/setup.sh to ~/.bashrc for automatic setup

Resources

• AMD XDNA Driver Repository
• XRT Documentation
• MOK Management: man mokutil

Thanks for the gist! This was my first time doing this kind of thing, and AI helpfully pointed out that in step 5, you have to run the following command to create a MOK if never done before:

sudo update-secureboot-policy --new-key 

(NOTE) you may safely ignore an error looking like:

Can't load /var/lib/shim-signed/mok/.rnd into RNG

Step 7: When running this command xrt-smi examine, I get the error:

...
EXE: /opt/xilinx/xrt/bin/unwrapped/xrt-smi

[xrt-smi] ERROR: mmap(addr=0x74ee00000000, len=67108864, prot=3, flags=8209, offset=4294967296) failed (err=-11): Resource temporarily unavailable

This is resolved with fix suggested in this readme section:

open /etc/security/limits.conf with sudo, and add the lines towards the end:

* soft    memlock    unlimited
* hard    memlock    unlimited

A couple other points:

1. My NPU firmware version is not 255.x.x.x

XRT
  Version              : 2.21.0
  Branch               : HEAD
  Hash                 : 92d731b2d6d2660b1ad407bb1bc0341d9a081fc1
  Hash Date            : 2026-01-03 21:37:29
  amdxdna              : 2.21.0_20260103, 273a5862044695357368f5226d7f527045a060fb
  virtio-pci           : 6.17.0-8-generic
  NPU Firmware Version : 1.1.0.60

2. I think you should correct the following in the Verifaction Commands section to this:

# Check MOK enrollment (if using Secure Boot)
mokutil --list-enrolled | grep "Secure Boot"

(i.e. remove the "mod")