Registry / ai-ml / onnx-graphsurgeon

onnx-graphsurgeon

JSON →
library0.6.1pypypi✓ verified 21d ago

ONNX GraphSurgeon is a Python library used for programmatically manipulating ONNX graphs. It provides a high-level API to import, inspect, modify, and export ONNX models, often used in conjunction with NVIDIA TensorRT for optimization and deployment workflows. The current PyPI version is 0.6.1, though its development is closely tied to TensorRT's release cadence, with newer versions often bundled with TensorRT distributions.

pip install onnx-graphsurgeon==0.6.1
INSTALL
IMPORT
SIG · ONNX-GRAPHSURGEON
O
onnx-graphsurgeon
ai-mlpythonv0.6.1
Install
7.0s avg
Import
526ms
Disk
181MB
Pass rate
5/ 10
Env Coverage5 / 10
glibc
3.93.13
musl
3.93.13
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
musl
py 3.103.95 runs
build_error
glibc
py 3.103.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.
fix
Check 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.
fix
Always 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.
fix
Explicitly 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.
fix
Install `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.
fix
Ensure 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.
fix
This 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.
fix
Ensure `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.
Agent activity
12 hits · last 30 days
node
8
Amazon
1
Resources