Install and deploy Windows ML

Windows ML ships as part of the Windows App SDK and supports two deployment modes: framework-dependent (recommended) and self-contained. Choose based on your app's size, update, and dependency requirements.

To learn more about Windows ML, see What is Windows ML.

Quick start

Here's the short version of how to install Windows ML in your project:

C#

For framework-dependent (recommended), install:

• Microsoft.WindowsAppSDK.ML
• Microsoft.WindowsAppSDK.Runtime
• Then, see Deployment for framework-dependent apps for how to deploy the runtime

For self-contained (increases app size by ~41 MB):

• For apps targeting Windows 10 Build 18362 or higher, install Microsoft.Windows.AI.MachineLearning
• Or, for apps targeting Windows 10 Build 17763 or higher, install Microsoft.WindowsAppSDK.ML
• Do not install Microsoft.WindowsAppSDK.Runtime or the main Microsoft.WindowsAppSDK package

C++/WinRT

For framework-dependent (recommended), install:

• Microsoft.WindowsAppSDK.ML
• Microsoft.WindowsAppSDK.Runtime
• Then, see Deployment for framework-dependent apps for how to deploy the runtime

For self-contained (increases app size by ~41 MB):

• For apps targeting Windows 10 Build 18362 or higher, install Microsoft.Windows.AI.MachineLearning
• Or, for apps targeting Windows 10 Build 17763 or higher, install Microsoft.WindowsAppSDK.ML
• Do not install Microsoft.WindowsAppSDK.Runtime or the main Microsoft.WindowsAppSDK package

C/C++

For self-contained (framework-dependent is not supported for C/C++), reference Microsoft.Windows.AI.MachineLearning and configure CMake to use its build/cmake directory. See Self-contained installation below for the full CMake setup.

Python

For framework-dependent, install the required packages:

pip install wasdk-Microsoft.Windows.AI.MachineLearning[all] wasdk-Microsoft.Windows.ApplicationModel.DynamicDependency.Bootstrap onnxruntime-windowsml

And then install the Windows App SDK Runtime that matches the version of the wasdk- packages.

For full details on each option, see the sections below.

Requirements

C#

• .NET 8 or greater
• Target framework moniker net8.0-windows10.0.17763.0 or greater if using Microsoft.WindowsAppSDK.ML, or target framework moniker net8.0-windows10.0.18362.0 or greater if using Microsoft.Windows.AI.MachineLearning

Note

With .NET 6, you can use the Microsoft.Windows.AI.MachineLearning namespace to install execution providers, but Microsoft.ML.OnnxRuntime APIs are not available. Upgrade to .NET 8 to access the full Windows ML API surface.

C++/WinRT

• C++20 or later

C/C++

• Visual Studio 2022 with C++ workload
• CMake 3.21 or later

Python

• Python 3.10–3.13 on x64 or ARM64
• An unpackaged Python installation (python.org or winget — not the Microsoft Store)

What's in Windows ML

Windows ML is composed of these binaries:

Binary	Description	Approx. size
Microsoft.Windows.AI.MachineLearning.dll	Windows ML APIs (ExecutionProviderCatalog, etc.)	~1 MB
onnxruntime.dll	The ONNX Runtime engine	~20 MB
DirectML.dll	DirectML — the included GPU execution provider	~20 MB
	Total	~41 MB

Vendor execution providers (QNN, VitisAI, OpenVINO, NvTensorRtRtx, MIGraphX) are not part of Windows ML itself. They are obtained separately — either via the ExecutionProviderCatalog at runtime, or bundled yourself. See Accelerate AI models.

Choosing a deployment mode

When using Windows ML, you can choose between two deployment modes: framework-dependent (recommended) and self-contained.

	Framework-dependent (recommended)	Self-contained
Supported languages	C#, C++/WinRT, Python	C#, C++/WinRT, C/C++
Supported packaging types	Unpackaged and packaged (MSIX)	Unpackaged and packaged (MSIX)
Enterprise deployment	Supported	Supported
App size	Smaller — Windows ML binaries are shared system-wide	Larger — Windows ML binaries are bundled with your app (~41 MB)
Windows ML updates	Automatic — users get updates via Windows App SDK servicing	Manual — you ship a new version when you choose
Dependency on installed runtime	Yes — Windows App SDK runtime must be present	No — all dependencies are in your app package
NuGet package (C#/C++)	Microsoft.WindowsAppSDK.ML + Microsoft.WindowsAppSDK.Runtime	Microsoft.Windows.AI.MachineLearning or Microsoft.WindowsAppSDK.ML
Best for	Apps that require a minimal download/install size; Apps shipping through the Microsoft Store	Strict version control

Framework-dependent installation (recommended)

Framework-dependent apps rely on the Windows App SDK runtime being installed on the user's machine. See Deployment architecture for framework-dependent apps for details.

C#

In your project, install or update the following NuGet packages:

• Microsoft.WindowsAppSDK.ML (this adds the Windows ML APIs)
• Microsoft.WindowsAppSDK.Runtime (this enables framework-dependent mode)

Note

Alternatively, install / update the main Microsoft.WindowsAppSDK NuGet package to version 1.8.1 or greater, which includes Windows ML and all other Windows App SDK APIs, and defaults to framework-dependent.

Also, in your .csproj file, ensure that WindowsAppSDKSelfContained is either unspecified (not present), or false, so that it uses framework-dependent deployment.

C++/WinRT

In your project, install or update the following NuGet packages:

• Microsoft.WindowsAppSDK.ML (this adds the Windows ML APIs)
• Microsoft.WindowsAppSDK.Runtime (this enables framework-dependent mode)

Note

Alternatively, install / update the main Microsoft.WindowsAppSDK NuGet package to version 1.8.1 or greater, which includes Windows ML and all other Windows App SDK APIs, and defaults to framework-dependent.

Also, in your project file, ensure that WindowsAppSDKSelfContained is either unspecified (not present), or false, so that it uses framework-dependent deployment.

C/C++

Framework-dependent C/C++ support is not currently available. Either use C++/WinRT, or self-contained as described below.

Python

Install the required packages:

pip install wasdk-Microsoft.Windows.AI.MachineLearning[all] wasdk-Microsoft.Windows.ApplicationModel.DynamicDependency.Bootstrap onnxruntime-windowsml

And then install the Windows App SDK Runtime that matches the version of the wasdk- packages.

Finally, see Deployment architecture for framework-dependent apps to learn how to deploy the Windows App SDK runtime to your user's devices alongside your app.

Self-contained installation

Self-contained apps bundle all Windows ML binaries directly in the app. No external runtime dependency is required, but your app will be larger. This is the default when you reference Microsoft.Windows.AI.MachineLearning or Microsoft.WindowsAppSDK.ML without referencing the main Microsoft.WindowsAppSDK or Microsoft.WindowsAppSDK.Runtime package. See Deployment guide for self-contained apps for details.

C#

In your project, install or update the following NuGet packages:

• For apps targeting Windows 10 Build 18362 or higher:
  • Install Microsoft.Windows.AI.MachineLearning (this adds the Windows ML APIs and binaries, defaults to self-contained)
• Or, for apps targeting Windows 10 Build 17763 or higher:
  • Install Microsoft.WindowsAppSDK.ML (this adds the Windows ML APIs and binaries, defaults to self-contained, and adds RegFree WinRT support for 17763)
• Do NOT install Microsoft.WindowsAppSDK.Runtime (this would enable framework-dependent mode... remove it if you currently have it installed)
• Do NOT install the main Microsoft.WindowsAppSDK NuGet package (this would enable framework-dependent mode... remove it if you currently have it installed)
• Feel free to install other Windows App SDK component packages like Microsoft.WindowsAppSDK.AI, as long as you don't install the Runtime or the main package

Note

If you must use the main Microsoft.WindowsAppSDK NuGet package, update it to version 1.8.1 or greater, which includes Windows ML and all other Windows App SDK APIs, and in your .csproj, set WindowsAppSDKSelfContained to true to enable self-contained mode.

C++/WinRT

In your project, install or update the following NuGet packages:

• For apps targeting Windows 10 Build 18362 or higher:
  • Install Microsoft.Windows.AI.MachineLearning (this adds the Windows ML APIs and binaries, defaults to self-contained)
• Or, for apps targeting Windows 10 Build 17763 or higher:
  • Install Microsoft.WindowsAppSDK.ML (this adds the Windows ML APIs and binaries, defaults to self-contained, and adds RegFree WinRT support for 17763)
• Do NOT install Microsoft.WindowsAppSDK.Runtime (this would enable framework-dependent mode... remove it if you currently have it installed)
• Do NOT install the main Microsoft.WindowsAppSDK NuGet package (this would enable framework-dependent mode... remove it if you currently have it installed)
• Feel free to install other Windows App SDK component packages like Microsoft.WindowsAppSDK.AI, as long as you don't install the Runtime or the main package

Note

If you must use the main Microsoft.WindowsAppSDK NuGet package, update it to version 1.8.1 or greater, which includes Windows ML and all other Windows App SDK APIs, and in your project, set WindowsAppSDKSelfContained to true to enable self-contained mode.

C/C++

The C APIs ship in the Microsoft.Windows.AI.MachineLearning NuGet package. The package includes CMake config files under build/cmake/ for direct consumption.

To use the NuGet package...

1. Download or restore the NuGet package (e.g., via nuget restore or manual download)
2. Extract or reference the package root directory
3. Set CMAKE_PREFIX_PATH to the build/cmake subdirectory of the package

Example CMakeLists.txt

cmake_minimum_required(VERSION 3.21)
project(MyApp LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

find_package(microsoft.windows.ai.machinelearning CONFIG REQUIRED)

add_executable(MyApp main.cpp)
target_link_libraries(MyApp PRIVATE WindowsML::Api WindowsML::OnnxRuntime)

add_custom_command(TARGET MyApp POST_BUILD
    COMMAND ${CMAKE_COMMAND} -E copy_if_different
        $<TARGET_RUNTIME_DLLS:MyApp> $<TARGET_FILE_DIR:MyApp>
    COMMAND_EXPAND_LISTS
    VERBATIM
)

Example build commands

# Point CMAKE_PREFIX_PATH to the NuGet package's cmake directory
cmake -B build -S . -DCMAKE_PREFIX_PATH="C:/packages/Microsoft.Windows.AI.MachineLearning/build/cmake"
cmake --build build --config Release

The NuGet package ships its own cmake config under build/cmake/ that understands the NuGet directory structure (architecture-specific directories under lib/native/ and runtimes/). Architecture is determined from CMAKE_GENERATOR_PLATFORM, CMAKE_VS_PLATFORM_NAME, or CMAKE_SYSTEM_PROCESSOR.

The vcpkg portfile generates a separate, thin config file that maps to the standard vcpkg layout (lib/ and bin/). Both configs share the same targets file (microsoft.windows.ai.machinelearning-targets.cmake) which defines the IMPORTED targets.

The same targets (WindowsML::WindowsML, WindowsML::Api, WindowsML::OnnxRuntime, WindowsML::DirectML) are available in both consumption modes. Use the standard CMake 3.21 $<TARGET_RUNTIME_DLLS> generator expression to copy runtime DLLs to the build output directory.

Python

Self-contained deployment is not applicable for Python. Use the framework-dependent pip packages described above.

Next step

Get started with Windows ML

See also

• What is Windows ML
• Windows App SDK deployment overview
• Windows ML samples