onnx2tf: ONNX to LiteRT, TensorFlow and PyTorch, With a Caveat in Its Own README

The artifact mismatch onnx2tf exists to remove

Model files travel between frameworks badly. A model trained and exported as an ONNX file is a graph with typed tensors and a declared opset. A TFLite or LiteRT file is a flatbuffer intended for on-device runtimes. A PyTorch nn.Module is Python source plus weights. None of these are interchangeable formats, and hand-porting a graph is slow and error-prone. onnx2tf takes the ONNX graph as the input and emits one of several targets: LiteRT/TFLite/TensorFlow, PyTorch native code as an nn.Module, TorchScript (.pt), a state_dict (.pt), an Exported Program (.pt2), and Dynamo ONNX. It also handles the reverse direction, LiteRT to PyTorch. The audience is narrow and practical: engineers who already have an ONNX file and need a different runtime artifact, usually for mobile or embedded deployment, or for a PyTorch codebase that has to consume a model exported from somewhere else. If your model already exists natively in the target framework, onnx2tf adds a round trip for no benefit.

What the operator table actually tells you

The README's main technical content is a layer support table keyed to the ONNX Operators list. Each entry carries one of three marks: a check for supported, a white check for partial support, and the words Help wanted for the rest. Reading the table is the fastest way to predict whether a conversion will work. Most of the arithmetic and normalization surface is fully marked: Conv, ConvTranspose, Gemm, MatMul, BatchNormalization, InstanceNormalization, GroupNormalization, LayerNormalization, the Reduce family, the comparison operators, and the recurrent ops GRU, LSTM and RNN. The partial entries are the ones to watch, because a partial mark is not a promise. Col2Im, ConvInteger, DeformConv, DFT, GridSample, HammingWindow, HannWindow, ImageDecoder, and MaxRoiPool carry the partial mark. GridSample and DeformConv matter for vision models with non-uniform sampling; DFT and the window functions matter for audio front ends. A model whose preprocessing depends on one of those operators is exactly the case where a conversion can produce something that loads but does not compute what you expect. The table is also a snapshot: the README does not state which ONNX opset the marks were assessed against, so treat the mark as a starting hypothesis, not a guarantee for your opset version.

Installation and the conversion entry point

The project is published on PyPI as onnx2tf, so the documented install path is a pip install of that package. The README's own metadata shows Python 3.12 in the badge, with a second badge reading Python 3.8, which suggests a range rather than a single pinned interpreter; the repository also lists a Docker topic, so a container path exists alongside the pip route. The conversion surface is described as tf_converter, and the README's section heading names it as the thing whose supported layers are listed. Beyond that, the supplied material does not give a worked command line, a Python API example, or a configuration key table. That is a real gap for an evaluator: you cannot tell from the README alone whether a given flag exists, what its default is, or how output format selection is expressed. The honest reading is that the operator table is well documented and the invocation surface is not, so the first hour of an evaluation will be spent in the repository's own source and examples rather than in the README.

The README recommends a different tool

The most consequential line in the documentation is near the top: you should use LiteRT Torch rather than onnx2tf, followed by links to google-ai-edge/litert-torch and google-ai-edge/ai-edge-quantizer. That is an unusual thing for a maintainer to write, and it should shape adoption decisions more than any feature list. The two projects differ in direction of travel. onnx2tf is a converter that takes ONNX as the hub format and fans out to LiteRT, TensorFlow and several PyTorch representations, plus a LiteRT to PyTorch path. LiteRT Torch, judging by its name and the way the README frames it, is the first-party route into the LiteRT ecosystem from PyTorch, and ai-edge-quantizer covers the quantization step that onnx2tf's topic list also mentions. If your pipeline is PyTorch to on-device LiteRT, the README is telling you that onnx2tf is not the intended path and that going through ONNX first adds a hop. onnx2tf remains the right shape when ONNX is genuinely your source of record and you need the fan-out, particularly the PyTorch-side outputs that a LiteRT-first tool would not produce.

Six output formats means six things to validate

onnx2tf does not emit one artifact; it emits a choice of several, and they are not equivalent. PyTorch native code as an nn.Module is readable Python, which is useful when you need to inspect or edit the graph, but it is also the format most sensitive to how a given operator was translated, because the translation is visible source. TorchScript (.pt) is a serialized form meant for execution without the Python definition. A state_dict (.pt) is weights only, with no graph, so it is only useful if you already have a matching module definition. An Exported Program (.pt2) is the newer export container. Dynamo ONNX is an ONNX output, which means a conversion can round-trip back to the format it started from. Each of these has a different consumer, and the README does not map operators to output formats, only operators to support status. A model that converts cleanly to TFLite may not convert cleanly to a state_dict, because the two targets have different notions of what a graph is. Plan to pick one target format first and validate it, rather than assuming the support table covers all of them equally.

Where onnx2tf is the wrong tool

Three cases stand out. First, any model that depends on a partially supported operator: the table marks Col2Im, DeformConv, GridSample, DFT, ImageDecoder and MaxRoiPool as partial, so a detection or audio model leaning on those should be treated as unproven until you have compared outputs numerically against the ONNX original. Second, any project whose source of truth is PyTorch rather than ONNX: the README's own recommendation points elsewhere, and inserting ONNX into the middle of a PyTorch to LiteRT pipeline adds a conversion step whose failure modes you now own. Third, anything that needs a documented, stable CLI contract. The supplied README does not publish command syntax or configuration keys, so a team that needs to script conversions against a frozen interface has less to pin to than the operator table's completeness might suggest. None of this makes the project unusable; it makes it a tool you adopt with a validation harness rather than on the strength of a support matrix.

Maintenance, releases and the MIT licence

The release cadence visible in the material is tight: 2.6.6 on 2026-07-19, 2.6.7 on 2026-07-20, and 2.6.8 on 2026-08-01, all inside a two-week window, with the latest push timestamp matching the 2.6.8 release. Frequent patch releases on a converter are a double-edged signal: operator coverage and fixes arrive quickly, and so does the need to re-run your conversion checks after an upgrade. Pin the version you validate against and re-validate on bump, because a converter's output is the thing your downstream runtime consumes. The licence is MIT, as stated in the repository metadata and shown by the licence badge. MIT is permissive, which generally means you can use, modify and redistribute the code with the copyright notice and permission notice preserved, but licence terms interact with your own dependencies and distribution model, so read the LICENSE file in the repository rather than treating a badge as the whole story. This is not legal advice. The repository also carries a DOI badge pointing to a Zenodo record, which gives the project a citable snapshot alongside the PyPI releases.

Editorial conclusion

Adopt onnx2tf when your source artifact is an ONNX file and your target is a TFLite/LiteRT model, a PyTorch nn.Module, TorchScript, a state_dict, an Exported Program, or Dynamo ONNX, and when the operator you depend on is marked supported in the README table. Do not adopt it for a greenfield LiteRT project: the README itself points to google-ai-edge/litert-torch and ai-edge-quantizer as the preferred route. Before committing, verify the exact ONNX opset and operator status for your model, check which PyTorch output format your downstream tooling consumes, and read the MIT licence text rather than relying on the badge.

Official sources

1. Issues
2. License: MIT
3. PINTO0309/onnx2tf on GitHub
4. README
5. Releases