onnx-tensorflow: running ONNX models through a TensorFlow backend

What onnx-tensorflow is for, and the two directions people confuse

ONNX is an open standard format for representing machine learning models. onnx-tensorflow is the TensorFlow backend for that format: it takes an ONNX model as input, converts it into a TensorFlow model, and then delegates execution to TensorFlow to produce the output. The README is explicit that this is one of two TensorFlow converter projects in the ONNX community and that they serve different purposes. onnx-tensorflow converts ONNX to TensorFlow. tf2onnx, the repository at onnx/tensorflow-onnx, converts TensorFlow to ONNX. If you have a saved TensorFlow graph and want an ONNX file, this project is the wrong one, and the README says so directly. The audience here is narrower than the topic list suggests: people who already hold an ONNX artifact, perhaps exported from another framework, and who need to run it inside a TensorFlow process or inspect the converted graph. The README also carries a notice that the repo is not actively maintained and will be deprecated, and asks anyone interested in becoming the owner to contact the ONNX Steering Committee. That notice sits at the top of the file, above the conversion instructions, which tells you how the maintainers want the project read.

How the ONNX-to-TensorFlow conversion actually runs

The mechanism is a two-stage pipeline rather than an interpreter. The ONNX model is first converted to a TensorFlow representation, and only then is it handed to TensorFlow for execution. That distinction matters when something goes wrong: a failure during graph construction is a converter problem, while a failure at run time is a TensorFlow problem, and the two produce different errors. The package is named onnx-tf and installs a console entry point of the same name, declared in setup.py, which maps to onnx_tf.cli:main. The source lives in the onnx_tf directory, with tests under test. The repository pins its expectations in two files at the top level: VERSION_NUMBER for the package itself and ONNX_VERSION_NUMBER for the ONNX release the master branch supports. setup.py reads ONNX_VERSION_NUMBER and turns it into a dependency of the form onnx>=<version>, so the ONNX requirement is encoded at install time and the README says users need not worry about it. TensorFlow is deliberately not in install_requires. The README explains why: users often have their own preference for a GPU or CPU variant, so the responsibility for a correct TensorFlow sits with the user. The stated requirement is TensorFlow version == 2.8.0, and TensorFlow 1.x is no longer supported.

Installing onnx-tf and a first conversion from the command line

The production install is a single pip command. The README notes that ONNX is an external dependency and that protoc should be available if you plan to install ONNX via pip. Because TensorFlow is not pulled in automatically, install the variant you want at version 2.8.0 yourself; nothing here will do it for you.

pip install onnx-tf

After that, the CLI entry point is available. The README gives this exact form, with an input ONNX file and an output path:

onnx-tf convert -i /path/to/input.onnx -o /path/to/output

The CLI documentation is a separate file in the repository at doc/CLI.md, so flags beyond -i and -o are not described in the README itself. If you would rather stay in Python, the README shows the backend path, which loads the model with the onnx package and prepares it for execution:

import onnx
from onnx_tf.backend import prepare

onnx_model = onnx.load("input_path")  # load onnx model
output = prepare(onnx_model).run(input)  # run the loaded model

prepare returns an object whose run method takes the input and returns the output. For a worked walkthrough, the README points to the OnnxTensorflowImport notebook in the onnx/tutorials repository, and the example directory in this repository contains onnx_to_tf.py and relu.py. For a development install, the README says to clone the repository, install TensorFlow >= 2.8.0 together with tensorflow-probability and tensorflow-addons, and run pip install -e . from the checkout.

Operator coverage is the real constraint, not the API

The conversion API is small enough to memorize. The risk is elsewhere. A converter has to map every ONNX operator in your graph onto something TensorFlow can execute, and the repository tracks that mapping in doc/support_status.md, labeled ONNX-TensorFlow Op Coverage Status. The README does not claim complete coverage, and it does not list which operators are missing; it points at that document. So the practical question before adopting this project is not whether prepare and run work, but whether your specific model uses only supported operators. A graph with one unsupported node can fail the whole conversion, and the failure will surface at conversion time rather than as a subtly wrong number later. This is a structural property of any graph-to-graph converter, not a defect unique to this one, but it means the support status document is the first thing to read and the last thing to trust blindly for a model you care about. The model zoo tests give some signal: test/test_modelzoo.py checks whether ONNX Model Zoo models validate against the ONNX specification and convert to a TensorFlow representation. The README states plainly that inference on the converted model is not tested there. A green model zoo result therefore means the graph converted, not that it computes the right answer.

Testing before you deploy, and what the test suite does not cover

The README recommends running the complete test suite before deploying onnx-tf, and warns that it needs significant hardware resources and typically takes between 15 and 45 minutes depending on configuration. The unit tests use Python's unittest module:

pip install pytest tabulate
python -m unittest discover test

Only the ONNX backend tests in test/backend/test_onnx_backend.py need pytest and tabulate, per the README. The model zoo tests are heavier. They assume the onnx/models repository is cloned into the project directory, then scan that directory for ONNX models and, for each one found, download the model, convert it, generate a test status, and delete the model. Running all of them takes at least an hour according to the README, and the models are stored with Git LFS, so LFS must be installed. Reports are generated in the system temporary directory by default, and `python test/test_modelzoo.py -h` lists the command line options. Reports from merged commits are published on the project wiki. None of this constitutes a correctness check on inference output, and the README says so. If your deployment depends on numerical agreement with an ONNX runtime, the test suite here will not establish it.

Where the maintenance notice and the version pin bite

Two facts sit awkwardly together. The README states the repo is not actively maintained and will be deprecated, and invites interested parties to contact the ONNX Steering Committee. The most recent tagged release is v1.10.0 from 2022-03-17, following v1.9.0 in 2021 and v1.8.0 in 2021. The last push to the default branch was on 2026-08-23, so commits do land, but a repository with a deprecation notice and no release in years is not a dependency to build a new pipeline on. The version pin compounds this. The README requires TensorFlow version == 2.8.0 exactly, which is an equality, not a floor. That pin is the single hardest constraint in the project: it decides your Python and CUDA situation before you write any conversion code, and it will not move with the rest of your stack. The pip dependency on ONNX is looser, generated as onnx>=<version> from ONNX_VERSION_NUMBER, so the ONNX side can drift forward while TensorFlow stays fixed. When an ONNX release changes an operator definition, that asymmetry is where breakage would appear first.

onnx-tensorflow against tf2onnx and onnxruntime

The README itself draws the comparison that matters most. onnx-tensorflow and tf2onnx are the two TensorFlow converter projects, and they point in opposite directions. Choose by the format you hold, not by which repository looks busier. The README also notes that the project joined forces with Microsoft to co-develop an ONNX TensorFlow frontend, and that current onnx-tf frontend users should migrate to tf2onnx, where that code was merged. That is a migration instruction from the maintainers to their own users, and it is the strongest statement in the document. The other obvious alternative is to skip conversion entirely and execute the ONNX model with an ONNX-native runtime. The README's own example, example/test_mnist_onnxruntime_stepping.py, has onnxruntime in its name, which suggests the project's own examples compare the two paths. The difference in approach is simple: converting to a TensorFlow graph gives you a TensorFlow artifact you can inspect, save and run inside a TensorFlow process, at the cost of a conversion step that can fail on unsupported operators. Running the ONNX model directly with an ONNX runtime avoids that conversion step altogether and removes the TensorFlow 2.8.0 pin, but leaves you outside the TensorFlow tooling. If your reason for being here is TensorFlow itself, conversion is the point. If it is only to get predictions, it is overhead.

Licence, version files and the cost of staying on this branch

setup.py declares the license as Apache License 2.0, while the repository metadata carries NOASSERTION because the LICENSE file is not machine-matched to a standard identifier. Read the LICENSE file in the repository root if the distinction matters to your review process; the Apache 2.0 declaration in setup.py is the maintainers' own statement of intent, but it is not legal advice and not a substitute for reading the file. On upgrade cost, three files control what you are actually running: VERSION_NUMBER for the package, ONNX_VERSION_NUMBER for the supported ONNX release, and Versioning.md for the project's own versioning description. setup.py also writes a generated version.py into onnx_tf at build time containing the version and the git revision, and marks it as not to be edited. That is useful for reproducing a bug report, because the installed package records the commit it was built from. The practical upgrade path is narrow. With a pinned TensorFlow 2.8.0, a deprecation notice, and no release since v1.10.0, upgrading means moving to a different tool rather than to a newer version of this one. Budget for that migration when you adopt, not when the pin breaks.

Editorial conclusion

Use onnx-tensorflow when you already have an ONNX file and a TensorFlow 2.8.0 environment and you need to inspect or execute that graph through TensorFlow, accepting that the repository describes itself as not actively maintained and slated for deprecation, and that the last push was on 2026-08-23 while the newest tagged release, v1.10.0, dates from 2022-03-17. Do not pick it as the start of a new conversion pipeline: check doc/support_status.md for your operators first, and if your goal is a TensorFlow-to-ONNX direction, the README points to tf2onnx instead.

Frequently asked questions

Official sources

1. Issues
2. onnx/onnx-tensorflow on GitHub
3. README
4. Releases