WinML CLI

Windows ML CLI is a command line tool for building portable, performant, and high-quality AI models for Windows ML. It takes you from a source model — whether from Hugging Face or your own pipeline — to a hardware-optimized artifact in a reproducible workflow.

Purpose-built for Windows hardware diversity, the CLI handles conversion, graph optimization, and compilation across AMD, Intel, NVIDIA, and Qualcomm targets. The CLI fits naturally into CI/CD pipelines so teams can validate and ship models easily.

---

What you can do

• Build once, run across hardwares. Compose your own workflow from primitive commands (export, analyze, optimize, quantize, compile), or use an auto-generated config with winml build - both produce portable models that run across hardware.
• Drill into the details. Deep insights into operator compatibility, shape mismatches, graph optimizations, and EP-aware tuning at any stage of the pipeline.
• AI-ready. CLI-driven tools with built-in skills, friendly to work with mainstream agents.

What you get out of the box

• All Windows ML EPs supported. Every supported execution provider is available behind the same commands.
• Curated model catalog. A verified set of models that run across all Windows ML EPs - a reliable starting point.
• Bring your own ONNX. Not only for converting from PyTorch - bring an existing ONNX model to get operator-compatibility insights and optimize it based on the analysis.
• Hub-hosted ONNX models. Reference pre-exported ONNX files on the Hugging Face Hub as <org>/<repo>/<path/to/file>.onnx (e.g. onnx-community/sam3-tracker-ONNX/onnx/vision_encoder_int8.onnx). Supported by winml config, winml build, winml run, winml serve, winml perf, and winml eval.

---

🎯 Getting Started

Prerequisites

Component	Details
Windows	Windows 11 24H2 or later (required for NPU support; earlier versions work for CPU/GPU)
Python	3.11
Package manager	uv
WinML CLI	PyPI

Installation

WinML CLI requires Python 3.11 and is distributed as a Python wheel. We recommend uv for fast, reproducible environment setup.

Windows on Arm: winml-cli supports x64 (AMD64) Python only. On an Arm64 device, install an x64 build of Python 3.11 so uv resolves the win_amd64 wheels — PyTorch and the Windows ML runtime packages publish no win_arm64 wheels, so native Arm64 Python fails during setup. The x64 interpreter runs under Windows emulation and works normally. Create the environment with an explicit x64 interpreter:

uv python install cpython-3.11-windows-x86_64-none
uv venv --python cpython-3.11-windows-x86_64-none

1. Create an environment

uv venv --python 3.11

Activate it:

# Windows (PowerShell)
.venv\Scripts\activate

# Windows (Git Bash / WSL)
source .venv/Scripts/activate

2. Install winml-cli

uv pip install winml-cli

3. Verify your environment

uv run winml sys --list-device --list-ep

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.

🚀 Quick Start

Inspect the model

Before downloading any models, confirm that winml-cli recognises the model:

uv run winml inspect -m microsoft/resnet-50

💡 Tip: Always inspect before build to catch unsupported architectures early.

Build the model

uv run winml build -m microsoft/resnet-50 -o resnet_out/ --no-quant

winml build runs all pipeline steps in sequence — export, optimize, quantize. You can start a model build without a config file, or provide one to configure each step in the sequence (see winml config to customize). All intermediate artifacts land in resnet_out/. For more details, see Output Layout - Windows ML CLI.

Benchmark the model

uv run winml perf -m resnet_out/model.onnx --device auto --iterations 50 --monitor

--device auto lets the CLI resolve the best available device on your machine — NPU first, then GPU, then CPU.

---

🔀 Try Other Ways

• Use with AI Agent — See details at Use with AI Agent - Windows ML CLI.
• UI Quickstart — See also UI Quickstart - Windows ML CLI.

---

📚 Learn More

• Full Documentation — Access the complete wiki for detailed guides, API references, and troubleshooting.
• Supported Models — Browse the curated catalog of verified models that run across all Windows ML EPs.
• Execution provider compatibility — Browse the compatible EP alias and device combinations.

---

🔒 Privacy & Telemetry

Official WinML CLI releases can collect unlinked pseudonymized usage telemetry to help improve the product. Telemetry is classified as Optional. A one-time prompt on your first run asks for consent (default: accept — press Enter to enable, type n to decline).

Control — edit %USERPROFILE%\.winml\config.json:

• Set telemetry.consent to "disabled" to opt out
• Set telemetry.consent to "enabled" to opt in
• Delete the file to re-show the first-run prompt on the next run

See docs/Privacy.md for the full list of what is and is not collected, event schemas, CI auto-disable behavior, and storage locations.

---

🤝 Contributing

We welcome contributions! Please see the contribution guidelines.

For feature requests or bug reports, please file a GitHub Issue.

Code of Conduct

See CODE_OF_CONDUCT.md.

License

This project is licensed under the MIT License.

Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.