Install & Compatibility
Where this runs
tested against v1.16.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 7.0s · import 0.494s · 176MB
182MB installed
● package 182MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
convert_float_to_float16
✓ from onnxconverter_common import float16
✗ from onnxconverter_common import float16
This quickstart demonstrates how to use `onnxconverter-common` to convert an ONNX model from float32 to float16 precision. This is a common optimization to reduce model size and potentially improve inference performance on compatible hardware. It creates a dummy ONNX model, converts it, and saves the result.
import onnx
from onnxconverter_common import float16
import os
# Create a dummy ONNX model for demonstration
# In a real scenario, you would load your model: model = onnx.load("path/to/model.onnx")
# Example: A simple Add operation
nodes = [onnx.helper.make_node("Add", ["input1", "input2"], ["output"]) ]
graph = onnx.helper.make_graph(
nodes,
"simple-graph",
[
onnx.helper.make_tensor_value_info("input1", onnx.TensorProto.FLOAT, [None, 2]),
onnx.helper.make_tensor_value_info("input2", onnx.TensorProto.FLOAT, [None, 2]),
],
[
onnx.helper.make_tensor_value_info("output", onnx.TensorProto.FLOAT, [None, 2]),
],
)
model_fp32 = onnx.helper.make_model(graph, producer_name="onnx-example")
# Convert the model to float16
model_fp16 = float16.convert_float_to_float16(model_fp32)
# Save the converted model
output_path = "dummy_model_fp16.onnx"
onnx.save(model_fp16, output_path)
print(f"FP32 model converted to FP16 and saved to {output_path}")
# Clean up the dummy file
os.remove(output_path)
Debug
Known issues
breakingBreaking changes in ONNX or ONNX Runtime can cause compatibility issues. Specifically, `v1.16.0` fixed an `onnx.mapping` reference for `onnx 1.19`, indicating tight coupling and potential breakage with unaligned ONNX versions.fixAlways install `onnxconverter-common` alongside compatible `onnx` and `onnxruntime` versions. Refer to the project's GitHub releases and ONNX Runtime compatibility matrix. Upgrade `onnxconverter-common` to the latest version to ensure compatibility with recent ONNX releases.
affects: <1.16.0 with ONNX >=1.19
gotchaSpecific `protobuf` versions have been critical dependencies, leading to conflicts. `v1.14.0` explicitly required `protobuf==3.20.2` due to security concerns, which often clashed with other libraries (e.g., TensorFlow) requiring different `protobuf` versions. While recent versions might be more flexible, `protobuf` version clashes remain a common footgun in the ONNX ecosystem.fixCarefully manage `protobuf` versions in your environment. If encountering conflicts, try pinning `protobuf` to a version compatible with both `onnxconverter-common` and other major dependencies (e.g., `tensorflow`, `onnx`). Virtual environments are highly recommended.
affects: All versions, especially around 1.14.0
gotchaFloat16 (FP16) conversion can be complex and may introduce accuracy issues or runtime errors. Common problems include `SubGraph` bugs, incorrect operator ordering, `Cast` node issues, and failures with specific ops (e.g., `RandomUniformLike`, `Resize`). The tool might also log warnings about FP32 truncation.fixWhen converting to FP16, always validate the converted model's accuracy and functionality. Utilize `convert_float_to_float16` arguments like `op_block_list`, `node_block_list`, and `keep_io_types` to fine-tune the conversion. Monitor for warning messages during conversion and check relevant GitHub issues for known limitations.
affects: All versions performing FP16 conversion
gotchaModels exceeding 2GB can hit Protobuf deserialization limits, leading to `ValueError: Message onnx.ModelProto exceeds maximum protobuf size of 2GB`. This is a limitation of the Protobuf format, not `onnxconverter-common` directly, but affects its usage with large models.fixFor models over 2GB, consider splitting the model, using external data storage for large tensors in ONNX, or exploring specific `onnxruntime` nightly builds or older `onnxruntime`/`onnxconverter-common` combinations that might have workarounds. The `auto_mixed_precision_model_path` function might help with large models.
affects: All versions, when dealing with very large ONNX models.
Upgrade
Version history
1.16.0latest on PyPI · released Aug 28, 2025
Audit
Dependencies
numpyrequiredCore numerical operations dependency for ONNX model manipulation.
packagingrequiredUsed for version comparisons and managing package metadata.
onnxrequiredRequired for working with ONNX graph structures and model definitions.
protobufrequiredCore dependency for ONNX model serialization and deserialization. Specific versions can be critical.
onnxruntimeoptionalCommonly used for inference and validation of ONNX models, especially after conversion or optimization. Its import is delayed to avoid mandatory dependency.