Install & Compatibility
Where this runs
tested against v0.1.0 · 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.10
✕ build_error
10/12 runs
py 3.11
✕ build_error
✓ 85.02s
py 3.12
✕ build_error
✓ 79.44s
py 3.13
✕ build_error
✓ 73.6s
py 3.9
✕ build_error
✕ timeout
5530MB installed
● package 5530MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ORTModelForSequenceClassification
✓ from optimum.onnxruntime import ORTModelForSequenceClassification
✗ from optimum.onnx import ORTModelForSequenceClassification
This quickstart demonstrates the core workflow: exporting a Hugging Face model to ONNX using `ORTModelForSequenceClassification.from_pretrained(export=True)`, saving the exported model and tokenizer, then loading the ONNX model and performing inference with the `optimum.onnxruntime.pipeline`.
import os
from optimum.onnxruntime import ORTModelForSequenceClassification
from optimum.onnxruntime import pipeline as ORTPipeline # Alias to avoid conflict with transformers.pipeline if imported
from transformers import AutoTokenizer
model_checkpoint = "distilbert-base-uncased-finetuned-sst-2-english"
save_directory = "./tmp/onnx_model"
# 1. Load a model from transformers and export it to ONNX
print(f"Exporting model {model_checkpoint} to ONNX...")
ort_model = ORTModelForSequenceClassification.from_pretrained(model_checkpoint, export=True)
tokenizer = AutoTokenizer.from_pretrained(model_checkpoint)
# 2. Save the ONNX model and tokenizer
os.makedirs(save_directory, exist_ok=True)
ort_model.save_pretrained(save_directory)
tokenizer.save_pretrained(save_directory)
print(f"Model and tokenizer saved to {save_directory}")
# 3. Load the exported ONNX model for inference
print(f"Loading ONNX model from {save_directory} for inference...")
loaded_ort_model = ORTModelForSequenceClassification.from_pretrained(save_directory, file_name="model.onnx")
loaded_tokenizer = AutoTokenizer.from_pretrained(save_directory)
# 4. Run inference using the Optimum ONNX Runtime pipeline
cls_pipeline = ORTPipeline("text-classification", model=loaded_ort_model, tokenizer=loaded_tokenizer)
results = cls_pipeline("I love using Hugging Face Optimum ONNX!")
print(f"Inference result: {results}")
# Example with a quantized model (if applicable)
# from optimum.onnxruntime.configuration import AutoQuantizationConfig
# from optimum.onnxruntime import ORTQuantizer
# qconfig = AutoQuantizationConfig.arm64(is_static=False, per_channel=False)
# quantizer = ORTQuantizer.from_pretrained(ort_model)
# quantizer.quantize(save_dir=save_directory, quantization_config=qconfig)
# loaded_quantized_model = ORTModelForSequenceClassification.from_pretrained(save_directory, file_name="model_quantized.onnx")
# cls_pipeline_quant = ORTPipeline("text-classification", model=loaded_quantized_model, tokenizer=loaded_tokenizer)
# results_quant = cls_pipeline_quant("I love using Hugging Face Optimum ONNX with quantization!")
# print(f"Quantized inference result: {results_quant}")
Debug
Known issues
gotchaDirect `onnxruntime` and `onnxruntime-gpu` installation conflicts. If you've installed one, ensure to `pip uninstall` it before installing the other to prevent package conflicts.fixRun `pip uninstall onnxruntime` before `pip install "optimum-onnx[onnxruntime-gpu]"` (or vice-versa).
affects: All versions
gotchaCompatibility with `torch.onnx.export` and specific PyTorch versions can be challenging. Patch releases often address these, so ensure `optimum-onnx` is up-to-date, especially when working with newer PyTorch or Transformers versions.fixKeep `optimum-onnx` updated. Check release notes for `torch` and `transformers` compatibility.
affects: <=v0.0.3 (historically, may recur)
gotchaOptimization and quantization techniques applied with Optimum ONNX are often hardware-specific. For instance, `int8` quantization might only be supported on CPUs, and switching hardware after optimization can lead to issues.fixVerify hardware support for desired optimization/quantization strategies. Re-optimize or re-quantize if deploying to different hardware.
affects: All versions
gotchaWhen loading a model for inference after export, ensure you load the ONNX model file (e.g., `model.onnx` or `model_quantized.onnx`) by specifying `file_name` in `ORTModelForXxx.from_pretrained`.fixAlways specify `file_name="model.onnx"` or `file_name="model_quantized.onnx"` when loading a saved ONNX model using `ORTModelForXxx.from_pretrained(save_directory, file_name=...)`.
affects: All versions
Upgrade
Version history
0.1.0latest on PyPI · released Dec 23, 2025
Audit
Dependencies
optimumrequiredCore optimization library that optimum-onnx extends.
transformersrequiredRequired for Hugging Face model integration and tokenizer utilities. Explicitly pinned versions are often required (e.g., >=4.36,<4.58.0).
onnxrequiredONNX format definition and tools.
onnxruntimeoptionalInference engine for ONNX models.