ONNX Runtime WebGPU Plugin Execution Provider

WebGPU Plugin Execution Provider for ONNX Runtime.

Prerequisites

This package provides the WebGPU plugin EP only. You must separately install an ONNX Runtime package (e.g. onnxruntime) of version 1.24.4 or later.

If the installed ONNX Runtime is incompatible, the plugin EP will report an error when its library is registered.

On Linux, a system Vulkan loader (libvulkan.so.1) must be installed and available at runtime.

Supported Platforms

Installation

pip install "onnxruntime>=1.24.4"
pip install onnxruntime-ep-webgpu

Usage

import numpy as np
import onnxruntime as ort
import onnxruntime_ep_webgpu as webgpu_ep

# Register the plugin EP library with ONNX Runtime
ort.register_execution_provider_library("webgpu", webgpu_ep.get_library_path())

# Discover WebGPU EP devices
# The WebGPU EP currently accepts one EP device. Select a physical Dawn adapter independently.
webgpu_ep_device = next((d for d in ort.get_ep_devices() if d.ep_name == webgpu_ep.get_ep_name()), None)
if webgpu_ep_device is None:
    raise RuntimeError("No WebGPU EP device found.")

# Create a session using the WebGPU EP
sess_options = ort.SessionOptions()
sess_options.add_provider_for_devices(
  [webgpu_ep_device],
  {"adapterIndex": "0"},
)
session = ort.InferenceSession("model.onnx", sess_options=sess_options)

# Run inference (replace shape/dtype/name to match your model)
input_data = np.zeros((1, 3, 224, 224), dtype=np.float32)
output = session.run(None, {"input": input_data})

adapterIndex is a zero-based index into Dawn's adapter enumeration for the requested backend, using the power preference as an ordering and selection hint. It selects a physical adapter; deviceId remains the ORT WebGPU context identifier and does not select a GPU. The default context owns one device per process, so use a separate process for each adapter, or supply a custom webgpuInstance/webgpuDevice pair for multiple devices in one process. Omit adapterIndex to retain Dawn's automatic adapter selection.

Troubleshooting

• No WebGPU EP device found — the plugin EP loaded but no compatible adapter was discovered. On Linux this usually means the Vulkan loader (libvulkan.so.1) is not installed; install it via your distribution's package manager. On Windows it may indicate a missing or outdated GPU driver.
• ORT runtime version "..." is below the minimum required version "1.24.4" — the installed onnxruntime package is older than 1.24.4. Upgrade with pip install --upgrade "onnxruntime>=1.24.4".