rustnn

A Rust implementation of the W3C WebNN API with pluggable execution backends.

---

[WARNING] EXPERIMENTAL - DO NOT USE IN PRODUCTION

rustnn is a development release (0.6.0). APIs change without notice.

---

What is rustnn?

• The WebNN API in Rust. MLContext, MLGraphBuilder, MLGraph, MLTensor and dispatch mirror the W3C WebNN JavaScript API. Every operation of the specification is available on the builder; rustnn-specific additions carry a rustnn_ prefix.
• Backends selected at context creation. ONNX Runtime, NVIDIA TensorRT-RTX, Apple CoreML, LiteRT and Huawei CANN, chosen from the WebNN accelerated and power-preference hints or forced with a backend hint.
• Graph interchange. Loads .webnn text and JSON graphs from webnn-graph and onnx2webnn, saves graphs with .safetensors weights, exports ONNX and CoreML models and, with their features, TensorRT engines, TFLite and CANN models.
• Conformance. The upstream WebNN Web Platform Tests run in-repo against the backends on every pull request; the nightly dashboard shows per-operation results.

Python users: the pywebnn package wraps rustnn. This repository contains no Python API; the scripts under examples/experimental/ only run exported ONNX models for parity checks.

Quick start

Version 0.6.0 is the first crates.io release of the WebNN MLContext API (the 0.5.x releases were the earlier converter and loader crate). Add it with a backend feature:

[dependencies]
rustnn = { version = "0.6", features = ["onnx-runtime"] }

To follow unreleased changes, depend on the repository instead: rustnn = { git = "https://github.com/rustnn/rustnn", features = ["onnx-runtime"] }.

use rustnn::mlcontext::{
    MLContext, MLContextOptions, MLGraphBuilder, MLNamedOperands, MLNamedTensors,
    MLOperandDescriptor, MLPowerPreference, MLTensorDescriptor,
};
use rustnn::operator_enums::MLOperandDataType;

fn main() -> rustnn::error::Result<()> {
    let options = MLContextOptions::new(MLPowerPreference::Default, false);
    let mut context = MLContext::create(&options)?;

    // y = relu(x + 1)
    let mut builder = MLGraphBuilder::new(&mut context)?;
    let descriptor = MLOperandDescriptor::new(MLOperandDataType::Float32, vec![2, 2]);
    let x = builder.input("x", &descriptor)?;
    let one = builder.constant_from_slice(&descriptor, &[1.0f32; 4])?;
    let sum = builder.add(x, one)?;
    let y = builder.relu(sum)?;
    let mut outputs = MLNamedOperands::new();
    outputs.insert("y", y);
    let mut graph = builder.build(&outputs)?;

    let tensor = MLTensorDescriptor::new(MLOperandDataType::Float32, vec![2, 2]);
    let x_tensor = context.create_tensor(&tensor.to_writable())?;
    let y_tensor = context.create_tensor(&tensor.to_readable())?;
    context.write_tensor(&x_tensor, &[-2.0f32, -1.0, 0.0, 1.0])?;

    let mut inputs = MLNamedTensors::new();
    inputs.insert("x", &x_tensor);
    let mut output_tensors = MLNamedTensors::new();
    output_tensors.insert("y", &y_tensor);
    context.dispatch(&mut graph, &inputs, &output_tensors)?;

    let mut result = [0.0f32; 4];
    context.read_tensor(&y_tensor, &mut result)?;
    assert_eq!(result, [0.0, 0.0, 1.0, 2.0]);
    Ok(())
}

The ONNX Runtime backend loads the ONNX Runtime 1.29 shared library from ORT_DYLIB_PATH; from the repository root, make onnxruntime-download fetches a matching release into target/onnxruntime/. Set the variable before running (export ORT_DYLIB_PATH=... in bash, $env:ORT_DYLIB_PATH = "..." in PowerShell). See Getting Started.

For Python examples, see the pywebnn repository.

C and C++ APIs

Warning

The C ABI and C++ wrapper are experimental and are not stable. Like rustnn's Rust APIs, they may change without backward compatibility. This especially applies to future APIs for host pointers and buffer ownership, GPU-to-host synchronization, and asynchronous execution. Pin a rustnn version or commit and expect to rebuild consumers when updating it.

The capi feature provides:

• A generated C11 header at <rustnn/rustnn.h> with opaque handles, status codes, logger initialization, concrete graph operations, and _with_options variants.
• A header-only C++17 RAII wrapper at <rustnn/rustnn.hpp>. The wrapper uses only the generated C API and does not depend on Rust implementation details.
• pkg-config and CMake package metadata generated and installed by cargo-c.

Install a local development package with cargo-c:

cargo install cargo-c
cargo cinstall \
  --features capi,onnx-runtime \
  --prefix="$PWD/target/rustnn-capi-install"

A consuming CMake project can then use:

find_package(rustnn CONFIG REQUIRED)
target_link_libraries(my_application PRIVATE rustnn::rustnn)

The repository includes equivalent C and C++ examples that construct, compile, and dispatch a small arithmetic graph. At least one runtime backend feature is required to run them. See the C/C++ examples guide for API usage, ownership rules, package layout, and exact build and run commands.

For Python examples, see the pywebnn repository.

Features

Feature	Backend
onnx-runtime	ONNX Runtime (CPU, GPU, NPU execution providers), all platforms
trtx-runtime	NVIDIA TensorRT-RTX (Linux, Windows); trtx-runtime-mock builds without a GPU
coreml-runtime	Apple CoreML (macOS)
burn-runtime-cpu	Burn NdArray CPU; select Backend::BurnCpu, no native runtime library required
litert-runtime	LiteRT / TensorFlow Lite; needs flatc at build time
cann-runtime	Huawei CANN on OpenHarmony; cann-runtime-mock for validation
dynamic-inputs	Dynamic dimensions bounded by a maximum size
webnn-runtime	Browser WebNN bindings for wasm32-unknown-unknown (in progress)
trtx-enterprise	The TensorRT backend linked against full TensorRT 10 (nvinfer) instead of TensorRT-RTX; RTX-only features such as CUDA graphs are compiled out. Used for validation, not a supported deployment target
native-examples	Compiles the large example programs

Full list and environment variables: crate docs (make docs-api) or Backends.

Command line

cargo run --features onnx-runtime -- examples/sample_graph.webnn                         # validate
cargo run --features onnx-runtime -- examples/sample_graph.webnn --export-dot graph.dot  # Graphviz
cargo run --features onnx-runtime -- examples/sample_graph.webnn --convert onnx --convert-output model.onnx
cargo run --features onnx-runtime -- examples/sample_graph.webnn --convert onnx --run-onnx

Documentation

• Documentation site with the user guide, architecture and development pages
• Rust API reference: make docs-api writes it to target/doc/rustnn/index.html; the site publishes it under /api/ and docs.rs builds it for each release
• Backend Operator Support, generated from the converters
• WPT conformance dashboard
• Changelog

Contributing

Contributions welcome! Please see:

• AGENTS.md - Project architecture and conventions
• docs/development/contributing.md - How to add features
• TODO.txt - Feature requests and known issues

Quick Contribution Guide:

1. Fork and create feature branch: git checkout -b feature/my-feature

2. Install hooks (optional): ./scripts/install-git-hooks.sh

3. Make changes and test: make test && make python-test

4. If a WPT expected-failure list needs to be updated (indicated by test failures), use the per-backend sync target, which regenerates {backend}_expected_failures.txt from a fresh run:

   • make wpt-sync-onnx
   • make wpt-sync-litert
   • make wpt-sync-coreml (macOS only)
   • make wpt-sync-trtx (requires an NVIDIA GPU)

   Review the diff before committing!

5. Format code: make fmt

6. Commit and push

License

Apache License, Version 2.0. See LICENSE.

Links

• GitHub: https://github.com/rustnn/rustnn
• crates.io: https://crates.io/crates/rustnn
• Python bindings: https://github.com/rustnn/pywebnn
• W3C WebNN specification: https://www.w3.org/TR/webnn/

Acknowledgments

• The W3C WebML Working Group for the specification
• The Chromium WebNN implementation, used as the reference for operator lowering
• Created by Tarek Ziade