ONNX Runtime DirectML

1.24.4 verified Fri May 01 auth: no python

ONNX Runtime with DirectML execution provider for hardware-accelerated ML inference on Windows devices with DirectX 12 compatible GPUs. Version 1.24.4 requires Python >=3.11 and is maintained by Microsoft. Release cadence follows ONNX Runtime releases.

pip install onnxruntime-directml

Common errors

error onnxruntime.capi.onnxruntime_pybind11_state.NotImplemented: DML provider is not supported in this build. ↓

cause The installed onnxruntime Python package does not include DirectML support. Only onnxruntime-directml includes the DML provider.

fix

Uninstall onnxruntime and install onnxruntime-directml: pip uninstall onnxruntime && pip install onnxruntime-directml.

error RuntimeError: Dll registration failed. The specified module could not be found. ↓

cause Missing Visual C++ Redistributable or DirectX runtime on the system.

fix

Install the latest Visual C++ Redistributable from Microsoft (https://aka.ms/vs/17/release/vc_redist.x64.exe) and ensure DirectX 12 is available.

error onnxruntime.capi.onnxruntime_pybind11_state.Fail: Load model from <path> failed: File is not a valid ONNX protobuf. ↓

cause The model file is corrupt or not in ONNX format, or the protobuf library version mismatch.

fix

Verify the model file with onnx.checker.check_model() after loading with onnx.load(). Ensure protobuf version is compatible (protobuf 3.x recommended).

Warnings

breaking Python 3.11 minimum required as of version 1.24.x. Older Python versions are unsupported. ↓

fix Upgrade Python to 3.11 or later, or use an older onnxruntime-directml version (but note older versions may lack features).

gotcha DirectML execution provider requires Windows 10/11 with DirectX 12 GPU. It will not work on Linux or macOS. Trying to use DmlExecutionProvider on unsupported OS raises an error. ↓

fix Check platform before using DirectML: import sys; if not sys.platform.startswith('win'): raise RuntimeError('DirectML requires Windows').

deprecated Using Oracle JDK is deprecated; only Liberica JDK is fully supported. The default JDK download in some documentation points to Oracle, which may cause compatibility issues. ↓

fix Use Liberica JDK 8 or 11 as the Java runtime for QuickSight.

gotcha Manually specifying the execution provider order can cause performance degradation if CPU provider is placed before DirectML. Setting providers list correctly is essential. ↓

fix Always place DirectML provider first: providers=['DmlExecutionProvider', 'CPUExecutionProvider'].

Imports

InferenceSession
wrong
```
from onnxruntime_directml import InferenceSession
```
correct
```
from onnxruntime import InferenceSession
```
Onnxruntime-directml does not expose its own InferenceSession; it uses the standard onnxruntime session. DirectML is enabled via session options.
SessionOptions
wrong
```
import onnxruntime_directml
```
correct
```
from onnxruntime import SessionOptions
```
SessionOptions is in the onnxruntime package, not a separate directml package.

Quickstart

Basic inference using DirectML provider. Ensure model.onnx exists and is compatible.

import onnxruntime
from onnxruntime import InferenceSession, SessionOptions

# Enable DirectML execution provider
options = SessionOptions()
options.enable_training = False
providers = ['DmlExecutionProvider', 'CPUExecutionProvider']
session = InferenceSession('model.onnx', options, providers=providers)
# Run inference
import numpy as np
input_name = session.get_inputs()[0].name
result = session.run(None, {input_name: np.random.randn(1, 3, 224, 224).astype(np.float32)})