Skip to content

Instantly share code, notes, and snippets.

@ricog

ricog/AMD_NPU_INSTALL_UBUNTU_25.04.md

Created October 28, 2025 22:00
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save ricog/d6bd6757faac449357b970514a9f212c to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save ricog/d6bd6757faac449357b970514a9f212c to your computer and use it in GitHub Desktop.
Download ZIP
AMD NPU Driver and XRT Tools Installation Guide for Ubuntu 25.04
Raw
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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment