Overview
xpu-smi is the command-line interface for Intel(R) XPU Manager.
It is built on top of the Intel Level-Zero driver stack and provides local GPU
management for Intel(R) Arc Pro Series GPUs.
Global Options
These options are available at the top level (without a subcommand), except
--timeout, which applies to every command and may appear anywhere on the command line:
- -h, --help
Print the help message and exit.
- -v, --version
Display version information, including CLI version, build ID, and Level Zero version.
- --list-gpus
Print one line per GPU (index, name, UUID) and exit.
- --all
In the default output, also list the idle runtime contexts a multi-GPU process holds on GPUs it is not using, as
xpu-smi ps --alldoes. Can be combined with--loop.
- --query-gpu=<fields>
Single-shot or looping per-field query.
<fields>is a comma-separated list of field names (e.g.temperature.gpu,power.draw). Runxpu-smi --query-gpuwith no fields to list all available field names.Related options used with
--query-gpu:- --id <n>, --device <n>
Select GPU by index or PCI BDF address.
- --loop[=<sec>]
Repeat query every
<sec>seconds (default:1).
- --loop-ms=<ms>
Repeat query every
<ms>milliseconds. Takes precedence over--loop.
- --count=<n>, -c <n>
Cap the number of loop iterations. Default: infinite.
- --format=<spec>
Output format:
csv[,noheader][,nounits].
- -f <path>, --file=<path>
Redirect output to a file instead of stdout.
- --timeout=<sec>, --timeout <sec>
Abort if
xpu-smimakes no progress for<sec>seconds, for example because a driver call does not return. Without the option the timeout is60seconds, plus5for each GPU on Linux: driver initialization and the firmware fields of--query-gpuanddumphandle one GPU after another, so they take longer on a host with more GPUs.0turns the timeout off; the maximum is86400. Time spent waiting between samples (--loop,dump -i,stats) does not count, so long-running loops are not affected.After half the timeout without progress, a warning on stderr names the phase that is stuck (for example
driver init) and how many seconds remain. On timeout,xpu-smirestores the terminal, prints the phase and one line per thread to stderr, and exits with code124.The timeout is suspended while firmware is being written (
updatefw) and while a GPU is being reset (config --reset,config --coldreset,amc --gpureset): a flash can take several minutes and a reset about one, and interrupting either can leave the card unusable or off the PCI bus. It starts again, with the full timeout, once the operation ends.
Synopsis
xpu-smi [Options]
xpu-smi [--all] [--loop[=<sec>]|--loop-ms=<ms>] [--count=<n>]
xpu-smi -v
xpu-smi -h
xpu-smi --list-gpus
xpu-smi --query-gpu=<fields> [--id <n>] [--loop[=<sec>]|--loop-ms=<ms>] [--count=<n>] [--format=csv[,...]]
xpu-smi <command> [command-options]
xpu-smi [--timeout=<sec>] ...
Default Output
Running xpu-smi with no arguments displays a GPU status summary of all detected devices,
followed by the processes using them.
Name is the device name the driver reports, without the words that every Intel device
name shares: the trademark signs, a leading Intel (kept when only Graphics or GPU
would be left), a Data Center GPU prefix and a trailing Graphics or GPU after the
model number. So Intel(R) Arc(TM) Pro B60 Graphics shows as Arc Pro B60, and a name
still too long for the column wraps at a space. A driver
that has no product name for a device reports Intel(R) Graphics [0x<PCI device ID>], shown as
Graphics [0x<PCI device ID>]; a newer driver may name it. Discovery and
--query-gpu=name show the full name.
GPU-Util is the utilization of the busiest engine on the device: the fraction of the
sample window during which that engine was executing work. It is not the average across
all engines — a workload that saturates the compute engine while leaving the media and
copy engines idle reports close to 100%, because the compute engine is the bottleneck.
Use Stats for the per-engine-class breakdown behind that figure.
Note
Engine utilization is read from the GPU’s busyness counters, which the kernel exposes
only to callers holding CAP_PERFMON (or CAP_SYS_ADMIN on older kernels).
GPU-Util shows N/A when they are inaccessible — typically an unprivileged user,
or a container started without the capability. Add it with
docker run --cap-add=PERFMON ..., or run the container privileged. N/A means
“not measurable here”, as opposed to 0%, which means the engines were idle.
Command Categories
Command |
Linux |
Windows |
Description |
|---|---|---|---|
Yes |
Yes |
Discover GPU devices and display device properties |
|
Yes |
Yes |
Display system topology and CPU/GPU connectivity |
|
Yes |
Yes |
Display GPU performance statistics |
|
Yes |
Yes |
Continuously dump raw GPU telemetry to stdout or file |
|
Yes |
No |
Check GPU component health status |
|
Yes |
Yes |
Get and change GPU settings |
|
Yes |
Yes |
Update GPU firmware (GFX, FDO, GFX_DATA, OP_CODE, OP_DATA, AMC, COMPOSITE) |
|
Yes |
No |
AMC (Add-in Card Management Controller) operations |
|
Yes |
No |
Create and manage virtual GPUs (SR-IOV) |
|
Yes |
No |
List processes using GPU resources |
|
Yes |
No |
Manage Intel Crash Log collection via the |
|
Yes |
No |
Collect GPU debug logs |
Output Formats
Most commands support two output formats:
Text (default): Human-readable tabular output
JSON (
-j/--json): Machine-readable JSON, suitable for scripting and automationXML (
topology -f <file>): System topology exported as an XML file (see Topology)
Device Identification
Most commands accept a device identifier via -d / --device / --id (subcommands) or --device / --id (--query-gpu). Devices can be
addressed by either:
Device ID: An integer index assigned by the driver (e.g.,
0,1)PCI BDF address: Bus/Device/Function notation (e.g.,
0000:4d:00.0)
A comma-separated list combining either form selects multiple devices in a
single invocation (e.g., -d 0,1,4 or -d 0,0000:4d:00.0). Most
subcommands that accept --device parse this list; duplicate entries are
de-duplicated and the requested order is preserved. Some operations still
require a single device or behave differently for multiple devices:
amcoperates on a single device only and does not accept a list.config --reset/config --coldresetact on a single device.healthproduces separate per-device output only when--listis used.
Refer to each subcommand’s page for its exact device-selection behavior.
–query-gpu Field Reference
--query-gpu accepts a comma-separated list of field names. Fields are grouped by
metric category. Run xpu-smi --query-gpu with no argument to print the live list.
Metric Groups (for --metrics )
Group Name |
Shortcut |
Description |
|---|---|---|
|
— |
Device identity fields (name, index, UUID, serial, driver/vbios version, PCI IDs) |
|
|
Memory total/used/free, read/write bandwidth, bandwidth utilization |
|
|
GPU, compute, render, media, copy engine utilization (%) |
|
|
GPU core, memory and composite temperatures, configured throttle/shutdown thresholds. Shortcut |
|
|
Card- and GPU-domain power draw, energy counters, power limits. Shortcut |
|
|
Current and max graphics/media clock frequencies, throttle reason |
|
|
PCIe link gen/width (max and current), TX/RX throughput, replay counter |
|
|
EU active/stall/idle percentages (Intel Xe only) |
|
|
Fan speed (%) |
|
— |
Scheduler mode |
|
— |
Whether each clock throttle reason is active |
|
— |
GPU clocks the frequency range can be set to |
|
— |
All metrics from all groups |
Multi-char combos expand character-by-character (e.g. pu = POWER + TEMPERATURE + UTILIZATION, put adds PCI, pum adds MEMORY).
Available Field Names
Field |
Unit |
Description |
|---|---|---|
|
— |
Sample timestamp |
|
— |
GPU device name |
|
— |
GPU device index |
|
— |
GPU UUID |
|
— |
Serial number |
|
— |
Level Zero user-mode driver version string |
|
— |
Kernel-mode driver release version ( |
|
— |
GFX firmware version (shown as GFX Firmware Version in the query report) |
|
— |
PCI BDF address |
|
— |
Graphics IP version, in hex; identifies the architecture and stepping |
|
— |
PCI device ID |
|
— |
PCI base class code, in hex: |
|
— |
PCI subclass code, in hex |
|
— |
What the device needs to keep working: |
|
— |
PCI subsystem device ID (Linux only) |
|
C |
GPU core temperature |
|
C |
Memory temperature |
|
C |
Composite temperature |
|
C |
Configured GPU core temperature at which the clock is throttled |
|
C |
Configured GPU core temperature at which the device shuts down |
|
C |
Highest temperature the driver says the GPU sensor can operate at |
|
C |
Highest temperature the driver says the memory sensor can operate at |
|
C |
Configured memory temperature at which the clock is throttled |
|
C |
Configured memory temperature at which the device shuts down |
|
W |
Card-domain power draw, averaged over the sampling interval |
|
W |
GPU-domain power draw, averaged over the sampling interval: compute engines only,
excluding memory and other card subsystems. |
|
W |
Card-domain power draw at this moment, as the driver reports it; needs a runtime and loader that support it, and root on CRI |
|
W |
Current power limit |
|
W |
Default power limit from device properties |
|
W |
Lowest power limit that can be set, from device properties |
|
W |
Memory-domain power draw at this moment, on devices with a memory power domain |
|
W |
Burst power limit (PL2), on devices that report one |
|
W |
Peak power limit (PL4), on devices that report one |
|
W |
Maximum power limit |
|
J |
Cumulative card-domain energy counter; the energy counterpart of |
|
J |
Cumulative GPU-domain energy counter; the energy counterpart of |
|
% |
Overall GPU utilization: the busiest engine on the device |
|
% |
Compute engine utilization |
|
% |
Render engine utilization |
|
% |
Media engine utilization |
|
% |
Busiest video decode/encode engine; one engine class does both on Linux, so they are not reported apart |
|
% |
Busiest video enhancement engine (scaling, color conversion) |
|
% |
Copy engine utilization |
|
% |
Memory bandwidth utilization |
|
MiB |
Total memory |
|
MiB |
Memory the driver keeps back: installed size minus |
|
MiB |
Used memory |
|
MiB |
Free memory |
|
kB/s |
Memory read bandwidth |
|
kB/s |
Memory write bandwidth |
|
% |
Memory bandwidth utilization |
|
us |
Time the GPU clock has been held back by any throttle reason; the Linux runtime does not count it |
|
— |
Performance factor (0-100) of the compute engines; 50 is balanced |
|
— |
Performance factor (0-100) of the media engines; 50 is balanced |
|
MHz |
Current graphics/SM clock |
|
MHz |
Current media/video clock |
|
MHz |
Max graphics clock |
|
MHz |
Max media clock |
|
MHz |
GPU core clocks the minimum and maximum of |
|
MHz |
GPU core clock the driver last requested from the hardware |
|
— |
Active clock throttle reason flags |
|
— |
Whether one throttle reason is active ( |
|
— |
Maximum PCIe generation |
|
— |
Current PCIe generation |
|
— |
Maximum PCIe link width |
|
— |
Current PCIe link width |
|
MiB |
Size of the device’s largest memory BAR, the window through which the host reaches its local memory |
|
— |
Resizable BAR on that BAR: |
|
— |
Maximum PCIe generation of the root port the device is under (Linux); a switch in between can limit the link further |
|
— |
Maximum PCIe link width of the root port the device is under (Linux) |
|
— |
PCIe correctable errors since the device was enumerated (AER, Linux) |
|
— |
PCIe uncorrectable non-fatal errors since enumeration (AER, Linux) |
|
— |
PCIe uncorrectable fatal errors since enumeration (AER, Linux) |
|
— |
PCIe REPLAY_NUM rollovers since enumeration (AER, Linux) |
|
— |
PCIe replay timer timeouts since enumeration (AER, Linux) |
|
— |
PCIe AtomicOp requests the device completes, e.g. |
|
— |
Whether the device may send PCIe AtomicOp requests: |
|
MB/s |
PCIe transmit throughput |
|
MB/s |
PCIe receive throughput |
|
kB/s |
PCIe transmit throughput (kB/s) |
|
kB/s |
PCIe receive throughput (kB/s) |
|
— |
PCIe replay error counter |
|
— |
SR-IOV virtual functions enabled on the physical function |
|
% |
EU array active percentage (Intel Xe only) |
|
% |
EU array stall percentage (Intel Xe only) |
|
% |
EU array idle percentage (Intel Xe only) |
|
% |
Fan speed percentage |
|
— |
Scheduler mode: timeout, timeslice or exclusive |