Install & Compatibility
Where this runs
tested against v1.17.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.940 runs
build_error
glibcpy 3.10–3.940 runs
installs and imports cleanly · install 24.6s · import 11.913s · 202MB
614MB installed
● package 614MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
tf2onnx
✓ import tf2onnx
✗ import tf2onnx
This quickstart demonstrates converting a simple Keras sequential model (saved as a TensorFlow SavedModel) to the ONNX format using `tf2onnx.convert.from_saved_model`. It includes saving the Keras model, performing the conversion, saving the ONNX output, and optionally verifying the ONNX model's validity.
import tensorflow as tf
import tf2onnx
from onnx.checker import check_model
import shutil
import os
# 1. Create a simple Keras model
model = tf.keras.models.Sequential([
tf.keras.layers.Dense(10, input_shape=(784,), activation='relu'),
tf.keras.layers.Dense(10, activation='softmax')
])
model.compile(optimizer='adam', loss='sparse_categorical_crossentropy', metrics=['accuracy'])
# 2. Save the Keras model in the TensorFlow SavedModel format
# This is the recommended approach for converting TF2 models.
tf.saved_model.save(model, "my_keras_model")
# 3. Convert the SavedModel to ONNX
# Specify input_signature and output_names for robust conversion.
onnx_model_proto, _ = tf2onnx.convert.from_saved_model(
"my_keras_model",
input_signature=[tf.TensorSpec([None, 784], tf.float32, name="input_0")],
output_names=["output_0"]
)
# 4. Save the ONNX model to a file
with open("model.onnx", "wb") as f:
f.write(onnx_model_proto.SerializeToString())
print("ONNX model converted and saved as model.onnx")
# Optional: Verify the ONNX model structure
try:
check_model(onnx_model_proto)
print("ONNX model is valid.")
except Exception as e:
print(f"ONNX model validation failed: {e}")
# Clean up created files/directories
shutil.rmtree("my_keras_model")
os.remove("model.onnx")
tf2onnx --version
Debug
Known issues
breakingTensorFlow Version Compatibility: `tf2onnx` closely tracks TensorFlow releases. Older `tf2onnx` versions may not support newer TensorFlow features, and newer `tf2onnx` versions might drop support for older TensorFlow versions. This often leads to conversion failures or incorrect model behavior if not aligned.fixEnsure your `tf2onnx` version is compatible with your installed `tensorflow` version. Check the `tf2onnx` release notes for specific TensorFlow version support. Upgrade both `tf2onnx` and `tensorflow` in tandem if encountering issues.
affects: <1.16.1 (for TF 2.14/2.15 support); general issue across all versions
gotchaProtobuf Version Conflicts: `tf2onnx` (and its dependencies like `onnx` and `tensorflow`) have strict and often conflicting requirements for the `protobuf` library. Installing incorrect `protobuf` versions can lead to 'module not found' errors, serialization issues, or obscure runtime crashes.fixAfter installing `tensorflow` and `onnx`, let `pip` resolve `protobuf` dependencies. If conflicts arise, consider using a virtual environment or explicitly pinning `protobuf` to a version known to work with your specific `tensorflow` and `onnx` versions (e.g., `pip install protobuf==3.20.3`).
affects: All versions, particularly problematic around `protobuf` major version bumps (e.g., 3.x to 4.x or different minor versions).
gotchaCustom TensorFlow Operations: TensorFlow models containing custom operations, layers, or complex control flow that do not have direct equivalents in the ONNX operator set will fail conversion. `tf2onnx` provides some fallback mechanisms but they are not exhaustive.fixSimplify your TensorFlow model to use standard operations where possible. For truly custom ops, you may need to implement a custom ONNX operator, or perform graph surgery (e.g., separate parts of the model for conversion).
affects: All versions
gotchaInput/Output Signature Mismatch: Incorrectly specifying input signatures (`input_signature`) or output names (`output_names`) during conversion, especially with `from_saved_model` or `from_graph_def`, can lead to truncated models, missing outputs, or graph extraction errors.fixAlways explicitly define `input_signature` and `output_names` when converting. Use tools like `saved_model_cli show` to inspect your TensorFlow SavedModel's input/output signatures and ensure they match the conversion parameters exactly.
affects: All versions
Upgrade
Version history
1.17.0latest on PyPI · released Mar 4, 2026
Audit
Dependencies
tensorflowrequiredRequired for loading and converting TensorFlow models.
onnxrequiredRequired for building and validating ONNX models.
onnxruntimeoptionalCommonly used for inference and verification of converted ONNX models.
protobufrequiredStrict version requirements often lead to conflicts; specific versions are required by both TensorFlow and ONNX.