Registry / ai-ml / onnx2tf

onnx2tf

JSON →
library2.6.8pypypi✓ verified 21d ago

onnx2tf is a versatile Python tool designed for converting ONNX model files into various target formats, including LiteRT, TFLite, TensorFlow SavedModel, PyTorch native code (nn.Module), TorchScript (.pt), state_dict (.pt), Exported Program (.pt2), and Dynamo ONNX. It also supports direct conversion from LiteRT to PyTorch. The library maintains a rapid release cadence, with version 2.4.0 being the latest stable release.

pip install onnx2tf
INSTALL
IMPORT
SIG · ONNX2TF
O
onnx2tf
ai-mlpythonv2.6.8
Install
28.8s avg
Import
5268ms
Disk
827MB
Pass rate
8/ 10
Env Coverage8 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.29.24 · 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
musl
glibc
py 3.10
✕ build_error
✓ 49.6s
py 3.11
✓ —
✓ 50.2s
py 3.12
✓ —
✓ 20.5s
py 3.13
✕ build_error
✓ 21.2s
py 3.9
✓ —
✓ 2.3s
827MB installed
● package 827MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

convert
import onnx2tf # ... then onnx2tf.convert(...)

This quickstart demonstrates the end-to-end process of defining a simple PyTorch model, exporting it to ONNX format, and then using `onnx2tf` to convert the ONNX model into a TensorFlow SavedModel. It highlights the primary `onnx2tf.convert()` function and the necessary input/output paths.

import onnx2tf import torch import torch.nn as nn import os # 1. Define a simple PyTorch model class SimpleModel(nn.Module): def __init__(self): super(SimpleModel, self).__init__() self.conv = nn.Conv2d(3, 16, 3, 1, 1) def forward(self, x): return self.conv(x) # 2. Instantiate and export to ONNX model = SimpleModel() dummy_input = torch.randn(1, 3, 224, 224) onnx_file_path = "simple_model.onnx" torch.onnx.export( model, dummy_input, onnx_file_path, opset_version=17, input_names=["input"], output_names=["output"], dynamic_axes={"input": {0: "batch_size"}, "output": {0: "batch_size"}} ) print(f"PyTorch model exported to {onnx_file_path}") # 3. Convert ONNX to TensorFlow SavedModel output_folder = "./converted_tf_model" os.makedirs(output_folder, exist_ok=True) onnx2tf.convert( input_onnx_file_path=onnx_file_path, output_folder_path=output_folder, # For TFLite conversion, you might add: # tflite_output_file_path="./converted_tf_model/model.tflite" ) print(f"ONNX model converted to TensorFlow SavedModel at {output_folder}") # Clean up generated ONNX file os.remove(onnx_file_path) # To use a specific backend for TFLite (e.g., the deprecated tf_converter): # onnx2tf.convert( # input_onnx_file_path=onnx_file_path, # output_folder_path="./converted_tf_model_tfconv", # tflite_output_file_path="./converted_tf_model_tfconv/model.tflite", # tflite_backend='tf_converter' # )
onnx2tf --version
Debug
Known issues
breakingStarting with v2.4.0, the default TFLite backend for `onnx2tf.convert()` and the CLI has switched from `tf_converter` to `flatbuffer_direct`. Code relying on the implicit `tf_converter` behavior for TFLite conversion will now use `flatbuffer_direct`.
fix
If you require the `tf_converter` backend for TFLite, explicitly set `tflite_backend='tf_converter'` in your `onnx2tf.convert()` call or use the `--tflite_backend tf_converter` CLI option.
affects: >=2.4.0
deprecatedThe `tf_converter` TFLite backend is deprecated starting from v2.4.0. While still available as an explicit option, users are encouraged to migrate to `flatbuffer_direct` as it may be removed in future versions.
fix
Update your conversion scripts to use the `flatbuffer_direct` backend, which is now the default, or keep an eye on release notes for its eventual removal if `tf_converter` is critical for your workflow.
affects: >=2.4.0
gotchaonnx2tf requires Python 3.12 or newer. Using older Python versions will lead to installation failures or runtime errors.
fix
Ensure your development environment uses Python 3.12 or a later version. You can manage Python versions using `pyenv` or `conda`.
affects: >=2.3.18
gotchaImplicit network downloads for validation sample data have been removed since v2.3.17. For integer quantization (`-oiqt`), explicit calibration input mapping is now required.
fix
When performing integer quantization, ensure you provide calibration inputs explicitly rather than relying on the library to download them. Refer to the documentation for the `--calibration_data_path` or equivalent API parameters.
affects: >=2.3.17
Errors
Common errors & fixes
ERROR: Unsupported ops: Counter({'OP_NAME': X})
The ONNX model contains an operator ('OP_NAME') that is not directly supported by onnx2tf or its underlying TensorFlow conversion mechanisms.
fix
Use `simple-onnx-processing-tools` to preprocess the ONNX model and replace the unsupported operator with a combination of supported operations, or modify the original model's architecture to avoid the problematic operator.
ValueError: Cannot take the length of shape with unknown rank.
The ONNX model has dynamic input dimensions (e.g., a batch size of `None` or other undefined dimensions), which TensorFlow's graph construction or `onnx2tf`'s internal shape calculations cannot resolve.
fix
Fix dynamic input dimensions to a static size during conversion using the `-b` (batch size) or `-ois` (overwrite input shape) options in the `onnx2tf` command. For example, `-b 1` for a fixed batch size of 1.
ModuleNotFoundError: No module named 'ai_edge_litert'
A crucial dependency for onnx2tf, `ai_edge_litert`, which is part of its modern backend for direct TFLite conversion, is not installed or accessible in the environment.
fix
Ensure `ai_edge_litert` is installed in your Python environment. This typically happens automatically with `pip install onnx2tf`, but if not, install it explicitly: `pip install ai-edge-litert`. Also, verify TensorFlow and onnxruntime are installed.
ValueError: Exception encountered when calling layer "tf.math.add_XX" (type TFOpLambda). Dimensions must be equal, but are X and Y for '{{node ...}}' with input shapes: [shape1], [shape2].
A dimension mismatch occurs during a TensorFlow operation (like `Add` or `Concat`) within the converted graph, often stemming from incorrect tensor layout handling (e.g., NCHW in ONNX versus NHWC in TensorFlow) or complex shape transformations.
fix
Investigate the ONNX graph for problematic operations that alter tensor dimensions unexpectedly. Utilize `onnx2tf`'s options for channel transposition (`-kt` or `-kat`) or provide a parameter replacement JSON file (`-prf`) to manually specify correct transpositions or shape manipulations for the problematic layers.
onnx2tf command not found
The onnx2tf executable is not installed, not in the system's PATH, or the virtual environment where it's installed is not active.
fix
Install it using `pip install onnx2tf`, then ensure your terminal is in the correct environment or its installation directory is in your PATH.
Upgrade
Version history
2.6.8latest on PyPI · released Aug 1, 2026
Audit
Dependencies
onnxrequiredRequired for ONNX model processing, core functionality.
tensorflowrequiredTarget format for conversion, essential for TensorFlow/TFLite outputs.
torchrequiredRequired for PyTorch related conversions and for creating ONNX models from PyTorch.
flatbuffersrequiredUsed for direct TFLite backend conversions.
numpyrequiredFundamental library for array operations in ML workflows.
onnx_tfrequiredDependency for ONNX to TensorFlow conversion components.
protobufrequiredUsed for serializing structured data, essential for model formats.
Agent activity
19 hits · last 30 days
node
17
Resources
onnx2tf — pip install onnx2tf · libregistry