Skip to content

Installation

Prerequisites

Component Details
Windows Windows 11 24H2 or later (required for NPU support)
Hardware Device with CPU, GPU, or NPU
Python 3.11
Package manager uv
Version control git

No NPU?

You can follow most of these docs without NPU hardware. All winml-cli commands accept --device auto and fall back to CPU or DirectML automatically. The tutorials document explicit CPU fallback paths.

Install

uv python install 3.11
uv pip install winml-cli

uv python install 3.11 downloads and pins the exact Python version the project requires. uv pip install winml-cli installs the latest release from PyPI into a managed environment. No separate venv activation is needed.

Windows on Arm requires x64 Python

winml-cli supports x64 (AMD64) Python only. On an Arm64 device, native Arm64 Python cannot install the dependencies because PyTorch and the Windows ML runtime packages publish no win_arm64 wheels — uv sync fails with an unsupported-platform error. Install an x64 build of Python 3.11 and point uv at it:

uv python install cpython-3.11-windows-x86_64-none
uv sync --locked --python cpython-3.11-windows-x86_64-none

The x64 interpreter runs under Windows emulation on Arm64 hardware; winml sys still reports the Arm64 machine, and the NPU/GPU/CPU providers work normally.

Install from source (for development)

If you want to contribute or run the latest unreleased code:

git clone https://github.com/microsoft/winml-cli.git
cd winml-cli
uv sync

Verify

winml sys

Expected output (abbreviated):

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

Environment
  Python Version    3.11.x
  OS                Windows 11
  Machine           AMD64

ML Libraries
  Library        Version   Status
  torch          2.x.x     OK
  onnx           1.x.x     OK

Available Devices (priority order)
  #1  NPU   ...
  #2  GPU   ...
  #3  CPU   ...

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

This command enumerates available compute devices and execution providers on your machine. If an expected device or execution provider is missing, winml sys is the right place to diagnose it. See winml sys for the full flag reference and troubleshooting tips.

Next steps