Install & Compatibility
Where this runs
tested against v0.10.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
py 3.13
✕ build_error
4/8 runs
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
get_library_path
✓ from onnxruntime_extensions import get_library_path
Used to register the custom operators library with ONNX Runtime sessions.
gen_processing_models
✓ from onnxruntime_extensions import gen_processing_models
Primary API for converting Hugging Face data processing classes (like tokenizers) into ONNX processing graphs.
OrtPyFunction
✓ from onnxruntime_extensions import OrtPyFunction
Used to wrap an ONNX model, making it callable like a Python function for inference.
PyOrtFunction
✓ from onnxruntime_extensions import PyOrtFunction
✗ from onnxruntime_extensions import OrtFunction
`PyOrtFunction` is the correct name for wrapping models or custom ops for inference from file or definition, as of recent versions. `OrtFunction` might have been used in older examples or internal contexts.
onnx_op
✓ from onnxruntime_extensions import onnx_op
Decorator for defining custom operators using Python functions.
This quickstart demonstrates the core functionality of onnxruntime-extensions: converting a Hugging Face tokenizer into an ONNX graph with custom operators, and preparing an ONNX Runtime session to use these extensions. It showcases how to set up `SessionOptions` to register the custom operations library and then use `gen_processing_models` to create an ONNX representation of a tokenizer. The resulting ONNX tokenizer model can then be used for pre-processing text data.
import onnxruntime as ort
from onnxruntime_extensions import get_library_path, gen_processing_models, OrtPyFunction
from transformers import AutoTokenizer # pip install transformers
import numpy as np
# 1. Register the custom operators library
so = ort.SessionOptions()
so.register_custom_ops_library(get_library_path())
# 2. Convert a Hugging Face tokenizer to an ONNX processing model
try:
hf_tokenizer = AutoTokenizer.from_pretrained("bert-base-uncased")
# gen_processing_models returns two models: pre-processing (index 0) and post-processing (index 1 if available)
tokenizer_onnx_model = OrtPyFunction(gen_processing_models(hf_tokenizer, pre_kwargs={})[0])
# 3. Prepare input and run inference with the ONNX tokenizer model
input_text = ["Hello, ONNX Runtime Extensions!"]
# The output from the tokenizer_onnx_model will be the tokenized IDs
input_ids = tokenizer_onnx_model(input_text)
print(f"Original Text: {input_text}")
print(f"Token IDs (first input): {input_ids}")
# Example: Running a simple ONNX model with the custom ops library
# This part assumes you have an ONNX model (e.g., 'model.onnx')
# For a full example, you'd typically load your ML model here
# and connect its inputs/outputs with the tokenizer's outputs.
# For demonstration, we'll just show a dummy inference session.
# Dummy ONNX model (replace with your actual model path)
# Create a dummy ONNX model for demonstration if not available
# Example: import onnx; import onnx.helper; import onnx.numpy_helper
# graph_nodes = [onnx.helper.make_node('Identity', ['input'], ['output'])]
# graph_inputs = [onnx.helper.make_tensor_value_info('input', onnx.TensorProto.INT64, [1, 10])]
# graph_outputs = [onnx.helper.make_tensor_value_info('output', onnx.TensorProto.INT64, [1, 10])]
# graph = onnx.helper.make_graph(graph_nodes, 'dummy_graph', graph_inputs, graph_outputs)
# dummy_model = onnx.helper.make_model(graph, producer_name='dummy_model')
# onnx.save(dummy_model, 'dummy_model.onnx')
# Simulate using a real ONNX model
# Create a minimal ONNX model for demonstration. In a real scenario, this would be a pre-trained model.
# For this example, we'll just use the tokenized IDs as a dummy input.
# If you have a .onnx model, you would do:
# sess = ort.InferenceSession("your_model.onnx", so)
# model_outputs = sess.run(None, {"model_input_name": input_ids})
# print(f"Model outputs: {model_outputs}")
print("Quickstart demonstrated converting a Hugging Face tokenizer to ONNX custom operators.")
except ImportError:
print("Please install 'transformers' for the full quickstart example: pip install transformers")
except Exception as e:
print(f"An error occurred: {e}")
Errors
Common errors & fixes
error: no matching distribution found for onnxruntime-extensions
This usually occurs on less common architectures (e.g., ARM-based processors) or specific Python versions for which pre-built wheels are not available on PyPI.
fixTry installing from source. Ensure you have a compatible C++ compiler toolchain (e.g., `gcc` >= 8.0 or `clang` for Linux/macOS) and then run: `python -m pip install git+https://github.com/microsoft/onnxruntime-extensions.git`.
[ONNXRuntimeError] : 2 : INVALID_ARGUMENT : Invalid rank for input: ... Got: X Expected: Y
The input tensor provided to an ONNX model or custom operator has an incorrect number of dimensions (rank) or incompatible shape compared to what the ONNX graph expects.
fixInspect the input requirements of your ONNX model or custom operator. Use `model.graph.input` (for ONNX models) or documentation for custom ops to determine the expected input shape and type. Reshape your NumPy array inputs using `np.reshape()` or `np.expand_dims()` to match.
ImportError: DLL load failed while importing onnxruntime_extensions: A dynamic link library (DLL) initialization routine failed.
This error on Windows typically indicates missing or incompatible dependencies for the underlying native library. For CUDA-enabled builds, `CUDA_PATH` might be unset or incorrect; for Conda, environment issues.
fixFor CUDA, ensure `CUDA_PATH` environment variable is correctly set to your CUDA toolkit installation. For general DLL issues, try reinstalling `onnxruntime` and `onnxruntime-extensions` in a clean environment, and ensure your system's Visual C++ Redistributables are up-to-date. If using Conda, try `conda install -c conda-forge onnxruntime` before `pip install onnxruntime-extensions`.
[ONNXRuntimeError] : 2 : INVALID_ARGUMENT : Unexpected input data type.
The data type of the input tensor (e.g., `np.float64`) does not match the expected data type of the ONNX model or custom operator (e.g., `float32`).
fixExplicitly cast your NumPy array inputs to the correct data type using `input_array.astype(np.float32)` or the expected type. ONNX Runtime typically expects `float32` (single precision) for floats.
Upgrade
Version history
0.15.2latest on PyPI · released Feb 4, 2026
Audit
Dependencies
onnxruntimerequiredRequired for ONNX model inference and custom operator registration.
onnxrequiredRequired for generating and manipulating ONNX graphs, especially with `gen_processing_models`.
transformersoptionalNeeded for converting Hugging Face tokenizers into ONNX custom operators using `gen_processing_models`.
numpyoptionalCommonly used for array manipulation with ONNX Runtime inputs/outputs.