Implementation:Onnx Onnx Update Model Dims

Knowledge Sources	Onnx_Onnx
Domains	Model Transformation, Deployment
Last Updated	2026-02-10 00:00 GMT

Overview

Concrete tool for programmatically updating the dimension sizes of an ONNX model's inputs and outputs, provided by the ONNX library.

Description

The update_inputs_outputs_dims function modifies the shape information of a model's input and output tensors to match specified dimension values. This is essential for adapting models to different deployment scenarios such as changing batch sizes, input resolutions, or sequence lengths without retraining.

The function supports three types of dimension specifications:

• Positive integers set a concrete (static) dimension value. The function validates that the new value does not contradict an existing dimension value, raising a ValueError if a conflict is detected.
• Strings set a symbolic dimension parameter name (dim_param), enabling dynamic dimensions. For example, setting a dimension to "batch" allows the runtime to accept any batch size.
• Negative integers trigger automatic generation of a unique dimension parameter name using the format <tensor_name>_<axis_index>. The function verifies that the generated name does not conflict with existing dimension parameters.

Internally, the function first collects all existing dimension parameter names from the model's inputs, outputs, and intermediate value_info entries into a set for conflict detection. It then iterates through each specified input and output, applying the dimension updates via the helper function update_dim. After all modifications are applied, onnx.checker.check_model is called to validate the resulting model.

Usage

Use this function when you need to modify the shape of a model's inputs or outputs for deployment. Common scenarios include: changing the batch dimension from a fixed size to dynamic, adjusting input resolution for different hardware targets, converting between static and dynamic shapes, and preparing models for serving systems that require specific dimension configurations.

Code Reference

Source Location

• Repository: Onnx_Onnx
• File: onnx/tools/update_model_dims.py

Signature

def update_inputs_outputs_dims(
    model: ModelProto,
    input_dims: dict[str, list[Any]],
    output_dims: dict[str, list[Any]],
) -> ModelProto

Import

from onnx.tools.update_model_dims import update_inputs_outputs_dims

I/O Contract

Inputs

Name	Type	Required	Description
model	ModelProto	Yes	The ONNX model whose input/output dimensions will be updated
input_dims	dict[str, list[Any]]	Yes	Dictionary mapping input tensor names to lists of dimension values. Each dimension can be: a positive int (static size), a str (symbolic dim_param), or a negative int (auto-generated dim_param)
output_dims	dict[str, list[Any]]	Yes	Dictionary mapping output tensor names to lists of dimension values, using the same format as input_dims

Outputs

Name	Type	Description
model	ModelProto	The same model object with updated dimension information, validated by onnx.checker.check_model

Dimension Specification Rules

Value Type	Example	Behavior
Positive int	3	Sets a fixed dimension value (dim_value). Raises ValueError if contradicts existing value
String	"batch"	Sets a symbolic dimension parameter (dim_param) for dynamic sizing
Negative int	-1	Auto-generates a unique dim_param name in the format "<tensor_name>_<axis>"

Usage Examples

import onnx
from onnx.tools.update_model_dims import update_inputs_outputs_dims

model = onnx.load("model.onnx")

# Set dynamic batch dimension and fixed spatial dimensions
input_dims = {
    "input_image": ["batch", 3, 224, 224],
}
output_dims = {
    "predictions": ["batch", 1000],
}
updated_model = update_inputs_outputs_dims(model, input_dims, output_dims)
onnx.save(updated_model, "model_dynamic_batch.onnx")

# Use auto-generated dim_param for unknown dimensions
input_dims = {
    "input_1": ["b", 3, "w", "h"],
    "input_2": ["b", 4],
}
output_dims = {
    "output": ["b", -1, 5],
}
updated_model = update_inputs_outputs_dims(model, input_dims, output_dims)

# Set all dimensions to concrete values
input_dims = {
    "input": [1, 3, 640, 640],
}
output_dims = {
    "output": [1, 100, 6],
}
updated_model = update_inputs_outputs_dims(model, input_dims, output_dims)

Related Pages

• Environment:Onnx_Onnx_Python_Runtime_Environment