Install & Compatibility
Where this runs
tested against v1.22.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
muslpy 3.10–3.95 runs
build_error
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 6.8s · import 0.446s · 174MB
180MB installed
● package 180MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
onnx.helper
✓ from onnx import helper
onnx.checker
✓ from onnx import checker
TensorProto
✓ from onnx import TensorProto
✗ from onnx.onnx_pb import TensorProto
TensorProto is directly available from the top-level 'onnx' package in recent versions; old imports might point to internal proto structures which can change.
This quickstart demonstrates how to programmatically create a simple ONNX model (Y = X + A), validate it using `onnx.checker`, and then save it to a `.onnx` file using the ONNX Python API. It also shows how to load the model back for inspection.
import onnx
from onnx import helper, checker, TensorProto
import numpy as np
import os
# Create a simple ONNX model: Y = X + A
# Define model inputs and outputs
X = helper.make_tensor_value_info('X', TensorProto.FLOAT, [None, 2])
A = helper.make_tensor_value_info('A', TensorProto.FLOAT, [2])
Y = helper.make_tensor_value_info('Y', TensorProto.FLOAT, [None, 2])
# Create a node for the Add operation
node_def = helper.make_node(
'Add',
inputs=['X', 'A'],
outputs=['Y'],
)
# Create the graph
graph_def = helper.make_graph(
[node_def],
'simple-add-model',
[X, A],
[Y],
)
# Create the model with specified opset_imports (e.g., opset 13)
# Opset 13 is commonly used and widely supported.
model_def = helper.make_model(
graph_def,
producer_name='onnx-example',
opset_imports=[helper.make_opsetid('', 13)]
)
# Check the model for validity
checker.check_model(model_def)
print('Model is valid!')
# Save the model to a file
model_path = 'simple_add_model.onnx'
onnx.save(model_def, model_path)
print(f'Model saved to {model_path}')
# Optional: Load the model back and print its structure
loaded_model = onnx.load(model_path)
print('\nLoaded model:\n', loaded_model.graph.node)
# Clean up the created file
# os.remove(model_path)
Debug
Known issues
breakingThe `model hub integration` feature was removed in ONNX v1.21.0. If your workflow relied on this integration, you will need to update your code to remove references to it. [cite: github_release_v1.21.0]fixRemove any code referencing the defunct model hub integration. Consult ONNX documentation for alternative model management or sharing methods.
affects: >=1.21.0
gotchaIncompatible ONNX Opset Versions: Models created with a specific ONNX opset version (e.g., opset 13) may not be compatible with older runtimes or frameworks that do not support that opset. This can lead to conversion failures or unexpected behavior during inference.fixAlways verify that the ONNX opset version used for exporting or creating the model aligns with the supported versions of your target runtime or framework. Use `helper.make_opsetid('', <version_number>)` to explicitly set the opset. affects: All versions
gotchaUnsupported Operations or Custom Layers: When converting models from deep learning frameworks (e.g., PyTorch, TensorFlow) to ONNX, certain custom layers or framework-specific operations may not have direct equivalents in the ONNX operator set. This will cause conversion to fail or produce incorrect models.fixReimplement unsupported operations using ONNX-compatible alternatives or define custom ONNX operators if the functionality is critical and cannot be approximated. Consult the ONNX operator schema for available operations.
affects: All versions
gotchaShape and Dimension Mismatches: ONNX requires strict tensor shape definitions. Models relying on dynamic input shapes or having inconsistent batch size definitions between frameworks can lead to validation or runtime errors.fixExplicitly define input shapes, and consider using fixed dimensions when possible during export. For dynamic shapes, ensure they are correctly specified in the ONNX graph using symbolic dimensions.
affects: All versions
gotchaMissing 'ml_dtypes' dependency: Starting around ONNX v1.19.0, `ml_dtypes` became a crucial dependency for handling advanced data types. If you are using `onnx` with `onnxruntime` (especially versions like 1.24) and encounter a `ModuleNotFoundError` for `ml_dtypes`, it means this dependency is missing.fixExplicitly install the `ml_dtypes` package: `pip install ml_dtypes`.
affects: >=1.19.0 (especially when paired with onnxruntime >=1.24)
gotchaONNX, and many of its C/C++-dependent libraries (like `ml_dtypes`), require C/C++ compilers and build tools (e.g., `g++`, `make`, `cmake`) during installation. Minimal Docker environments, such as `python:3.13-alpine`, typically lack these tools by default, leading to build failures. The error `command 'g++' failed: No such file or directory` or `CMake Error: CMake was unable to find a build program` indicates these essential tools are missing in the environment.fixInstall the necessary build tools in your Dockerfile or environment. For Alpine Linux, use `apk add build-base cmake`. For Debian/Ubuntu, use `apt-get update && apt-get install -y build-essential cmake`.
affects: All versions (especially in Alpine-based images)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'onnx'
This error occurs when the 'onnx' Python package is not installed in the active environment or is not accessible to the Python interpreter.
fixEnsure `onnx` is installed using pip: `pip install onnx` or `pip install onnx==1.21.0` for a specific version. If using `onnxruntime`, install it with `pip install onnxruntime`.
[ONNXRuntimeError] : 2 : INVALID_ARGUMENT : Got invalid dimensions for input
This error typically indicates a mismatch between the input tensor's shape or rank provided during inference and the shape/rank the ONNX model expects.
fixInspect the ONNX model's expected input shape using `sess.get_inputs()[0].shape` and ensure your input NumPy array (e.g., `x.shape`) matches these dimensions. Reshape your input data accordingly, for example: `input_data = input_data.reshape(expected_shape)`. Also, verify the data type (e.g., `numpy.float32`) matches the model's expectation.
[ONNXRuntimeError] : 1 : FAIL : Load model from model.onnx failed
This error signifies that the ONNX Runtime was unable to load the specified model file, which can be due to a corrupted file, an incorrectly exported model, or incompatibility with the ONNX Runtime version.
fixVerify the integrity of the ONNX model using `onnx.checker.check_model('model.onnx')`. If it fails, re-export the model from its original framework, ensuring the correct ONNX exporter and opset version are used. Confirm the ONNX model version is compatible with your installed ONNX Runtime version. onnx.onnx_cpp2py_export.checker.ValidationError: No Op registered for ... with domain_version of ...
This validation error occurs when an ONNX model contains an operator that is not recognized or supported by the ONNX checker for the specified opset version or domain, often indicating a custom operator or an opset mismatch.
fixEnsure all custom operators are correctly registered or that the model only uses standard ONNX operators. Check the opset version of the exported model and try to re-export it with a widely supported opset version. If it's a known operator, update your `onnx` package to a version that supports it.
ImportError: DLL load failed while importing onnx_cpp2py_export: A dynamic link library (DLL) initialization routine failed.
This Windows-specific error typically means that `onnx` or `onnxruntime` cannot load its underlying C++ shared libraries, often due to missing Visual C++ Redistributable packages, an unset `CUDA_PATH` environment variable for GPU versions, or conflicts with other installed packages.
fixInstall the latest Microsoft Visual C++ Redistributable. If using a CUDA-enabled version, ensure the `CUDA_PATH` environment variable is correctly set to your CUDA toolkit installation directory. Sometimes, downgrading the `onnx` package (e.g., `pip install onnx==1.16.1`) can resolve conflicts.
Upgrade
Version history
1.22.0latest on PyPI · released Jun 15, 2026
Audit
Dependencies
pythonrequiredMinimum required Python version for recent ONNX releases.
ml_dtypesoptionalIntroduced around v1.19.1 to support additional machine learning data types (e.g., bfloat16, int4) in NumPy arrays for the reference evaluator and helper functions, improving interoperability.