XRT: the runtime layer between your application and an AMD NPU or FPGA

What the runtime layer actually is

FleXible RunTime, abbreviated XRT, is described as the run time for AIE and FPGA based platforms, and it is implemented as a combination of user-space and kernel driver components. Its job is to provide an abstracted runtime software interface for AMD NPUs and AMD FPGAs, so that an application talks to one API rather than to a specific board.

The list of supported hardware is the first thing to check, and it is broad. The interface covers AMD Ryzen client processors, AMD Ryzen Embedded, AMD Versal Adaptive SoCs, AMD Alveo Adaptable Accelerator Cards, and AMD Zynq UltraScale+ MPSoCs. A single runtime spanning a desktop processor, an embedded part, a standalone accelerator card and a heterogeneous SoC is the actual claim, and it is what makes a portable application possible on that hardware family.

The host side is equally specific. XRT runs on both Linux and Windows, hosted on x86_64 or aarch64 host CPU architectures. The host architecture matters more than it might seem, because an aarch64 host running a Versal board is a different deployment from an x86_64 workstation with an Alveo card, and the runtime supports both.

The driver model differs by operating system, and that difference is a design fact rather than an implementation detail. On Linux XRT uses the accel driver model, and on Windows it uses the MCDM driver model. Two different kernel models behind one user-space interface is exactly the kind of thing that makes a runtime layer worth having.

The layers are drawn in a diagram in the source documentation, and the project points at it from the top of the readme, which suggests the layering is meant to be understood before the API is.

xrt-smi is the first tool to reach for

XRT ships with a command line tool, xrt-smi, which may be used to examine, configure and validate NPU and FPGA devices. That single sentence covers the three jobs a bring-up engineer has on day one.

Examine is the query role: what devices are attached, what state are they in, what resources does each one expose. Configure is the setup role: setting a device up for the workload you are about to run. Validate is the check that the thing is alive and reachable before you spend an afternoon debugging your own application, which is the failure mode that costs the most time.

The reason to call this out separately from the library is that a runtime for accelerators is only as useful as the tooling around it. A hardware API without a way to interrogate the hardware is a library you debug by writing applications. xrt-smi is the tool that lets you narrow a problem down to your code rather than to the board, the driver or the firmware, and it is the piece most likely to be missing from a comparable project.

The API itself is delivered as header files, with the XRT API headers linked from the repository under src/runtime_src/core/include/xrt. Header-only distribution of the interface is what lets an application link against the runtime without a version-locked shared object in the middle, and the path tells you where the interface lives in the tree.

The documentation entry points are all in the same place. There are system requirements, build instructions, the main documentation site, and the API header reference, all under the project's documentation host, and the readme is deliberately a pointer document rather than a manual.

Two version schemes in the same tag list

The release history is unusual enough that a team pinning a version needs to look at it carefully. The recent releases are 2.25.0 from 2026-08-18, 202610.2.23.244 labelled the Official 2026.1 release from 2026-10-12, and 202610.2.23.0_Canonical from 2026-04-16.

There are two shapes of version number in that list, and they do not obviously belong to the same scheme. One is a plain three-part number, 2.25.0, and the other two start with a year and month, 202610 for October 2026, followed by a build sequence. The tag with the _Canonical suffix is a third variant again.

What this tells you is that the project publishes more than one flavour of artefact from the same tree, and the naming encodes the flavour. A team that pins 2.25.0 is pinning something different from a team that pins 202610.2.23.244, and the two are not interchangeable. This is a common pattern in vendor-adjacent runtime stacks where one numbering tracks the toolchain and the other tracks the platform release, but it is a trap for anyone who assumes a single version axis.

The dates also tell a story about the release rhythm. The 2026.1 release is dated 2026-10-12 and the 2.25.0 tag is dated 2026-08-18, so the two schemes were cut about two months apart. The last push to the repository was on 2026-10-19, one week after the 2026.1 release, so the working tree is already ahead of the newest official tag.

The CHANGELOG.rst at the root of the repository is the file to read when you need to know what a given tag contains, and the presence of a changelog file in a project of this size is a good sign.

How the source tree is laid out

The repository listing is compact, which is worth noting for a project of this scale. At the top level there is src/, build/, docs/, tests/, a CMakeLists.txt, a CHANGELOG.rst, a CONTRIBUTING.rst, a NOTICE file, a LICENSE file, a .clangd configuration and a pyrightconfig.json.

Several of those files describe how the project is built and checked rather than what it contains. CMakeLists.txt is the build entry point. .clangd is a clangd configuration, which is the language server that drives editor tooling for C++ and it is a sign the project expects contributors to work in an editor with completion and diagnostics rather than a bare build. pyrightconfig.json does the same job for TypeScript, which implies there is TypeScript somewhere in the tree even though the primary language is C++. The .gitmodules file says there are submodules, so part of the source is pulled in from elsewhere rather than living in this repository.

The .github/ directory is where the automation lives, and the readme carries a Coverity Scan badge, which points at a static analysis project for the code. Static analysis at that level is normal for a runtime that talks to kernels and to hardware, where an out-of-bounds access is a crash on a device rather than an exception in a service.

The split into src, build, docs and tests tells you where the four concerns live, and the separation of docs into its own directory, with the API header documentation generated from the headers themselves, is what keeps the two from drifting.

Where XRT is the wrong choice

The first limitation is that this is a runtime for specific AMD hardware, not a portable acceleration framework. The interface exists to give one API across Ryzen, Versal, Alveo and Zynq. If your application should run on an NVIDIA GPU, an Intel discrete card, or a CPU, this runtime is not in the picture, and there is no portable subset of it that is.

The second is the scope of what the runtime does. The documentation points to system requirements and build instructions rather than to a programming model, and the readme itself is a pointer document. What is described is the layer that provides access to devices, along with a device inspection tool. Anything you would call a programming model, whether that is kernels, a graph API or a memory model for the AI Engine array, belongs to the toolchain and the platform rather than to this repository.

The third is the coupling to the platform toolchain. The topic list includes vitis, and the release naming refers to an official platform release, which means the runtime is versioned against a vendor platform release cycle. That is the right way to version a runtime that must match firmware, drivers and hardware, and it is also a coupling you inherit: the version you can install is determined by what the platform supports, and a machine with an older board is not going to run the newest tag.

The fourth is the licensing. The project description records the licence as one that GitHub cannot classify, and the readme carries an SPDX-License-Identifier of Apache-2.0 in its source header along with Xilinx copyright for 2019 to 2022 and Advanced Micro Devices copyright for 2022 to 2026. A project with a custom licence file that also states an Apache-2.0 identifier is worth reading the actual file before you put it in a shipping product, because the copyright holders here are two companies that changed names during the period the code covers.

The fifth is that the two version schemes described earlier make pinning harder than it should be. A team that wants reproducible deployments has to record which flavour of which tag it uses, and the repository does not present that as a single axis to choose from.

Editorial conclusion

XRT fits a team that has chosen an AMD NPU or FPGA accelerator and needs a portable runtime rather than a board-specific driver, since the same API covers client Ryzen, embedded Ryzen, Versal adaptive SoCs, Alveo cards and Zynq UltraScale+ MPSoCs, and the accel driver model on Linux and MCDM on Windows cover the two host operating systems. It is the wrong choice if you have no AMD accelerator, if you need CUDA-style programming rather than a runtime, or if you need a library that a small team can maintain. Before adopting it, read the system requirements and build instructions in the linked documentation, confirm your host architecture and operating system are in scope, and pin a release deliberately, because the repository carries two version schemes and the last push was on 2026-10-19 with the official 2026.1 release dated 2026-10-12.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. Xilinx/XRT on GitHub