Install & Compatibility
Where this runs
tested against v0.6.1 · 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.526s · 175MB
181MB installed
● package 181MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
gs
✓ import onnx_graphsurgeon as gs
Common alias for convenience.
Graph
✓ from onnx_graphsurgeon.ir.graph import Graph
✗ from onnx_graphsurgeon import Graph
While often re-exported, the canonical path is through `ir.graph`.
Node
✓ from onnx_graphsurgeon.ir.node import Node
✗ from onnx_graphsurgeon import Node
While often re-exported, the canonical path is through `ir.node`.
Tensor
✓ from onnx_graphsurgeon.ir.tensor import Tensor
✗ from onnx_graphsurgeon import Tensor
While often re-exported, the canonical path is through `ir.tensor`.
This quickstart demonstrates how to load an ONNX model, find a specific node (Identity), remove it, and replace it with a new operation (an 'Add' node with a new constant input), and then save the modified model. It also includes `onnx.checker.check_model` for basic graph validation.
import onnx
import onnx_graphsurgeon as gs
from onnx import helper, TensorProto
import numpy as np
import os
# 1. Create a dummy ONNX model for demonstration
def create_dummy_model():
X = helper.make_tensor_value_info('X', TensorProto.FLOAT, [1, 3, 16, 16])
Y = helper.make_tensor_value_info('Y', TensorProto.FLOAT, [1, 3, 16, 16])
const_val_tensor_1 = helper.make_tensor('const_add_val_1', TensorProto.FLOAT, [], [1.0])
# Model: X -> Add (with const_add_val_1) -> Add_Output -> Identity -> Y
node_add = helper.make_node('Add', ['X', 'const_add_val_1'], ['Add_Output'])
node_identity = helper.make_node('Identity', ['Add_Output'], ['Y'])
graph_def = helper.make_graph(
[node_add, node_identity],
'simple_graph',
[X],
[Y],
[const_val_tensor_1]
)
model = helper.make_model(graph_def, producer_name='dummy-model', opset_imports=[helper.make_opsetid("", 13)])
return model
# Save the dummy model to a file
dummy_model = create_dummy_model()
onnx.save(dummy_model, "dummy_model.onnx")
print("Original model saved to dummy_model.onnx")
# 2. Load the model with ONNX GraphSurgeon
graph = gs.import_onnx(onnx.load("dummy_model.onnx"))
# 3. Modify the graph: Replace the Identity node with a second Add node
identity_node = None
for node in graph.nodes:
if node.op == "Identity":
identity_node = node
break
if identity_node:
input_tensor = identity_node.inputs[0] # Output of the first Add node
output_tensor = identity_node.outputs[0] # The graph's final output tensor 'Y'
# Remove the old Identity node
graph.nodes.remove(identity_node)
# Create a new Constant for the second Add op
const_val_tensor_2 = gs.Constant(name="const_add_val_2", values=np.array([2.0], dtype=np.float32))
# Create a new Add node to replace Identity
new_add_node = gs.Node(
op="Add",
inputs=[input_tensor, const_val_tensor_2], # Input from first Add, plus new constant
outputs=[output_tensor] # Re-use the original output tensor 'Y'
)
# Add the new node to the graph
graph.nodes.append(new_add_node)
# Always cleanup and topological sort after graph modifications
graph.cleanup().toposort()
# 4. Save the modified model
modified_model = gs.export_onnx(graph)
onnx.save(modified_model, "modified_dummy_model.onnx")
print("Modified model saved to modified_dummy_model.onnx (Identity replaced with Add)")
# Optional: Verify the modified model with ONNX checker
try:
onnx.checker.check_model(modified_model)
print("Modified model check successful!")
except Exception as e:
print(f"Modified model check failed: {e}")
# Cleanup created files
os.remove("dummy_model.onnx")
os.remove("modified_dummy_model.onnx")
Debug
Known issues
breakingThe PyPI package `onnx-graphsurgeon` (v0.6.1) might be significantly older than the version integrated with current NVIDIA TensorRT releases (e.g., TensorRT 10.x). For optimal compatibility, especially with new ONNX operators or TensorRT features, it is often recommended to use the `onnx-graphsurgeon` version bundled with your specific TensorRT installation or build from source.fixCheck TensorRT documentation for recommended installation methods. Consider building from the TensorRT GitHub repository or using the version provided with your TensorRT distribution instead of pip installing.
affects: PyPI versions vs. bundled TensorRT versions
gotchaONNX GraphSurgeon does not automatically validate the semantic correctness of graph modifications. Incorrect changes can lead to invalid ONNX graphs that fail `onnx.checker.check_model()` or cannot be parsed/optimized by runtimes like TensorRT.fixAlways use `onnx.checker.check_model()` after graph modifications to verify structural integrity. Perform runtime validation (e.g., with ONNX Runtime or TensorRT) to confirm functional correctness.
affects: All versions
gotchaCareful management of `gs.Tensor` objects (inputs/outputs) is crucial during graph manipulation. Incorrectly linking tensors or failing to update consumer/producer relationships can result in a broken graph. Using `graph.cleanup().toposort()` is essential after modifications.fixExplicitly manage `gs.Tensor` inputs/outputs when adding/removing nodes. Always call `graph.cleanup().toposort()` to remove disconnected nodes/tensors and ensure a valid topological order.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'onnx_graphsurgeon'
The 'onnx_graphsurgeon' module is not installed in the Python environment, or it was not installed from the correct NVIDIA PyPI index, especially on platforms like Jetson.
fixInstall `onnx-graphsurgeon` using pip with the NVIDIA PyPI index: `python3 -m pip install onnx_graphsurgeon --extra-index-url https://pypi.ngc.nvidia.com` or `python3 -m pip install onnx_graphsurgeon --index-url https://pypi.ngc.nvidia.com`.
AttributeError: 'Variable' object has no attribute 'values'
The `values` attribute can only be accessed on `onnx_graphsurgeon.Constant` tensors, not on `onnx_graphsurgeon.Variable` tensors, which represent unknown values until inference time.
fixEnsure you are trying to access `values` only on tensors confirmed to be `Constant` types. If you need to modify a variable's data, you might be incorrectly treating it as a constant or need to convert it to a Constant first if its value becomes known.
UnicodeDecodeError: 'utf-8' codec can't decode byte 0x80 in position 0: invalid start byte
`onnx-graphsurgeon` attempts to decode a `STRING` type attribute (e.g., from `TRT_PluginV2` nodes) as a UTF-8 string, but the attribute contains raw binary data that is not valid UTF-8.
fixThis issue is often due to an older version of `onnx-graphsurgeon`. Updating to a newer version that correctly handles binary `STRING` attributes, or a manual workaround to prevent decoding specific attributes, is necessary. The fix often involves internal changes to `onnx-graphsurgeon`'s import logic.
This ORT build has ['TensorrtExecutionProvider', 'CUDAExecutionProvider', 'CPUExecutionProvider'] enabled. Since ORT 1.9, you are required to explicitly set the providers parameter when instantiating InferenceSession. For example, onnxruntime.InferenceSession(..., providers=['TensorrtExecutionProvider', 'CUDAExecutionProvider', 'CPUExecutionProvider'], ...)
When using `graph.fold_constants()` in `onnx-graphsurgeon`, which internally relies on `onnxruntime.InferenceSession`, the `providers` argument is not explicitly passed to the `InferenceSession` constructor, a requirement for `onnxruntime` versions 1.9 and newer.
fixEnsure `onnxruntime` is configured correctly, and if directly calling `onnxruntime.InferenceSession`, always explicitly provide the execution providers. While `fold_constants` abstracts this, upgrading `onnx-graphsurgeon` or ensuring compatible `onnxruntime` versions can resolve this.
Upgrade
Version history
0.6.1latest on PyPI · released Apr 8, 2026
Audit
Dependencies
onnxrequiredRequired for ONNX model parsing and generation.
flatbuffersrequiredUsed for internal data serialization.