Install & Compatibility
Where this runs
tested against v0.7.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
build_error
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 12.5s · import 2.008s · 243MB
263MB installed
● package 263MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
script
✓ from onnxscript import script
The primary decorator to mark a Python function for ONNX conversion.
opsetXX
✓ from onnxscript import opset15 as op
Import specific ONNX opsets (e.g., opset15, opset17) to access ONNX operators as Python functions.
FLOAT
✓ from onnxscript.onnx_types import FLOAT
Used for type annotations to specify ONNX tensor types. Other types like INT64, BOOL are also available.
This quickstart demonstrates defining a simple ONNX function `MatmulAdd` using the `@script` decorator and ONNX operators from `opset15`. It shows how to use type annotations for inputs and outputs, evaluate the function in eager mode, convert it to an ONNX ModelProto, and save it to a file. The example includes basic input data generation and ONNX model validation.
import onnx
from onnxscript import script, FLOAT
from onnxscript import opset15 as op
import numpy as np
# Define an ONNX function using the @script decorator
@script()
def MatmulAdd(X: FLOAT['N', 'K'], Wt: FLOAT['K', 'M'], Bias: FLOAT['M',]) -> FLOAT['N', 'M']:
return op.MatMul(X, Wt) + Bias
# Create some dummy input data
x_data = np.random.rand(64, 128).astype(np.float32)
wt_data = np.random.rand(128, 10).astype(np.float32)
bias_data = np.random.rand(10,).astype(np.float32)
# Evaluate the ONNX Script function in eager mode (for debugging/testing)
result_eager = MatmulAdd(x_data, wt_data, bias_data)
print(f"Eager mode output shape: {result_eager.shape}")
# Convert the ONNX Script function to an ONNX ModelProto
model_proto = MatmulAdd.to_model_proto(
(x_data, wt_data, bias_data), # Example inputs for tracing shapes
output_names=['output']
)
# Save the ONNX model
onnx_file_path = "matmul_add_model.onnx"
onnx.save(model_proto, onnx_file_path)
print(f"ONNX model saved to {onnx_file_path}")
# Optionally, check the model for validity
try:
onnx.checker.check_model(model_proto)
print("ONNX model is valid!")
except onnx.checker.ValidationError as e:
print(f"ONNX model validation error: {e}")
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'onnxscript'
The `onnxscript` package is not installed or is not accessible in the current Python environment, often occurring when it's an indirect dependency for other libraries like PyTorch's ONNX exporter.
fixEnsure `onnxscript` is installed in your active environment: `pip install --upgrade onnxscript` or `pip install -U onnx onnxscript` if using with `torch.onnx`.
ONNXRuntimeError: [ONNXRuntimeError] : 9 : INVALID_ARGUMENT : Node input type mismatch
There is a discrepancy between the data type or shape of the input provided to an ONNX model and the expected data type or shape defined in the model's graph when using ONNX Runtime for inference.
fixVerify the ONNX model's input specifications (data types, shapes) and ensure your input data is correctly pre-processed to match these expectations. You can inspect the model's input signature using the `onnx` Python API.
ValueError: Required inputs (['X']) are missing from input feed (['misspelled'])
The input names provided to the ONNX Runtime session for inference do not match the input names expected by the ONNX model, often due to a typo or misunderstanding of the model's input signature.
fixInspect your ONNX model to identify the exact input names (e.g., using `model.graph.input` in the `onnx` Python API) and ensure the dictionary or feed used for inference provides data with these matching names.
TypeError: Descriptors cannot be created directly. If this call came from a _pb2.py file, your generated code is out of date and must be regenerated with protoc >= 3.19.0.
This error typically indicates an incompatibility between the `protobuf` library version and the generated Python files (`_pb2.py`) used by `onnx` (which `onnxscript` relies on), meaning the generated code is out of date for the installed `protobuf` version.
fixDowngrade the `protobuf` package to a compatible version (e.g., `protobuf<=3.20.x`) or, if possible, regenerate the `_pb2.py` files with `protoc >= 3.19.0`.
pattern rewrite error: Unexpected onnxscript value type '<class 'onnxscript.ir.Value'>'
This error occurs when attempting to use the `onnxscript.rewriter` functionality with an unexpected or incompatible value type during pattern matching or replacement.
fixReview the rewrite pattern and replacement function to ensure that all intermediate values and operations are correctly handled as `onnxscript` types (e.g., `onnxscript.ir.Value`) and that the pattern correctly identifies the nodes and attributes it intends to manipulate.
Upgrade
Version history
0.7.1latest on PyPI · released Jun 29, 2026
Audit
Dependencies
onnxrequiredCore dependency for ONNX graph representation and manipulation. ONNX Script builds upon the ONNX standard.
numpyrequiredCommonly used for array operations in Python functions that are then converted to ONNX.
onnx-irrequiredUtilized for the Abstract Syntax Tree (AST) conversion and intermediate representation in newer versions.
ml-dtypesoptionalHandles machine learning specific data types.