winml sys¶

Inspect your machine — devices, EPs, and runtime versions at a glance.

When to use this¶

Run winml sys before starting any export or build workflow to confirm that the required ML libraries are installed and that the target hardware is visible. It is also the first command to run when diagnosing an unexpected export failure.

Synopsis¶

$ winml sys [options]

Flags¶

Flag	Short	Type	Default	Description
`--format`	`-f`	`text` \| `json` \| `compact`	`text`	Output format. `text` renders rich tables, `json` emits machine-readable JSON, `compact` prints a single-line summary.
`--list-device`	—	flag	`false`	List available compute devices (NPU, GPU, CPU) in priority order instead of showing the full system report.
`--list-ep`	—	flag	`false`	List available ONNX Runtime execution providers instead of showing the full system report. Can be combined with `--list-device`.
`--verbose`	`-v`	flag	`false`	Surface additional diagnostic sections: backend availability and Export Readiness.
`--help`	`-h`	flag	—	Show help and exit.

winml sys takes no --model, --device, --ep, --task, or --precision arguments. It describes the host environment, not a specific model.

How it works¶

winml sys queries Python's platform and importlib.metadata modules to report library versions. On Windows, it also reads the native HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion registry key to report the display version, build, update build revision (UBR), build branch, and build lab. It then probes PyTorch for CUDA availability and GPU device names. Backend availability checks use the installed runtime environment. GPU and NPU enumeration uses DXCore as the source of adapter identity and LUID, then enriches those native rows with WMI/PnP driver and manufacturer details. CPU enumeration uses WMI. Devices remain in NPU > GPU > CPU priority order, and EP enumeration merges the WinML EP registry with ONNX Runtime's get_available_providers(). When --format json is used the full report — including devices and EPs — is emitted as a single JSON object, making it easy to capture in CI pipelines.

Within the GPU class, devices are ordered by ONNX Runtime hardware metadata DxgiHighPerformanceIndex numerically (0 first), with LUID as a stable tie-breaker. This is the Windows DXGI high-performance preference, not DXCore enumeration order. The preference is joined to native DXCore rows by LUID; EP metadata never adds or removes physical adapters. Missing or invalid ranks sort after ranked GPUs, in LUID order. If EP probing cannot supply ranks, all native GPUs fall back to LUID order.

Unpinned runtime GPU selection uses the same ordering within the selected EP source's exposed devices. An EP that exposes only a subset of installed GPUs can therefore select a different GPU from the first system-wide row. An explicit --device-luid on winml perf overrides that preference.

Examples¶

# Full human-readable system report
$ winml sys

+------------------------------------+
|   winml-cli System Information     |
+------------------------------------+

Environment
  Python Version    3.11.9
  Python Executable C:\...\python.exe
  OS                Windows 11
  Machine           AMD64
  Display Version   24H2
  Current Build     26100
  UBR               4946
  Build Branch      ge_release
  BuildLabEx        26100.1.amd64fre.ge_release.240331-1435

ML Libraries
  Library        Version   Status
  torch          2.4.0     OK
  transformers   4.44.0    OK
  onnx           1.16.1    OK
  ...

Available Devices (priority order)
  #1  NPU   Qualcomm(R) Hexagon NPU
             LUID: 0x00000000_0x00018393 | Driver: 1.0.0 | Manufacturer: Qualcomm
  #2  GPU   Qualcomm(R) Adreno GPU
             LUID: 0x00000000_0x00018394 | Driver: 1.0.0 | Manufacturer: Qualcomm
  #3  CPU   Snapdragon(R) X Elite
             LUID: N/A | Cores: 12 | Threads: 12 | Architecture: ARM64

Available Execution Providers
  QNNExecutionProvider           -> NPU/GPU
  DmlExecutionProvider           -> GPU
  CPUExecutionProvider           -> CPU

# Compact one-liner — useful for CI logs
$ winml sys --format compact

# Machine-readable JSON — pipe to jq or save for later comparison
$ winml sys --format json > env.json

The full JSON report includes a schema version and installed physical memory:

{
  "schema_version": 1,
  "platform": {
    "system": "Windows",
    "release": "11",
    "machine": "ARM64"
  },
  "memory": {
    "physical_total_mib": 16384
  }
}

Memory capacity uses MiB. If the host does not expose the physical memory total, the field is null and winml sys emits a warning while preserving the rest of the system report.

# Only list devices — skip everything else
$ winml sys --list-device

# List EPs as JSON — useful for scripting EP selection
$ winml sys --list-ep --format json

Common pitfalls¶

--list-device and --list-ep suppress the full report. When either flag is present, only the requested section is printed. Omit both flags to see the complete system report.
--format compact omits device and EP tables. The compact format is designed for single-line log entries and does not include device or EP details. Use text or json when you need the full picture.
CUDA shown as unavailable on a machine with a GPU. PyTorch must be installed with CUDA support (torch+cuXXX). A CPU-only torch wheel will always report cuda_available: false.