Functions#

torch.onnx.export(model,args=(),f=None,*,kwargs=None,verbose=None,input_names=None,output_names=None,opset_version=None,dynamo=True,external_data=True,dynamic_shapes=None,custom_translation_table=None,report=False,optimize=True,verify=False,profile=False,dump_exported_program=False,artifacts_dir='.',fallback=False,export_params=True,keep_initializers_as_inputs=False,dynamic_axes=None,training=<TrainingMode.EVAL:0>,operator_export_type=<OperatorExportTypes.ONNX:0>,do_constant_folding=True,custom_opsets=None,export_modules_as_functions=False,autograd_inlining=True)[source]

Exports a model into ONNX format.

Settingdynamo=True enables the new ONNX export logicwhich is based ontorch.export.ExportedProgram and a more modernset of translation logic. This is the recommended and default way to export modelsto ONNX.

Whendynamo=True:

The exporter tries the following strategies to get an ExportedProgram for conversion to ONNX.

1. If the model is already an ExportedProgram, it will be used as-is.

2. Usetorch.export.export() and setstrict=False.

3. Usetorch.export.export() and setstrict=True.

Parameters:

• model (torch.nn.Module |torch.export.ExportedProgram |torch.jit.ScriptModule |torch.jit.ScriptFunction) – The model to be exported.

• args (tuple[Any,...]) – Example positional inputs. Any non-Tensor arguments will be hard-coded into theexported model; any Tensor arguments will become inputs of the exported model,in the order they occur in the tuple.

• f (str |os.PathLike |None) – Path to the output ONNX model file. E.g. “model.onnx”. This argument is kept forbackward compatibility. It is recommended to leave unspecified (None)and use the returnedtorch.onnx.ONNXProgram to serialize the modelto a file instead.

• kwargs (dict[str,Any]|None) – Optional example keyword inputs.

• verbose (bool |None) – Whether to enable verbose logging.

• input_names (Sequence[str]|None) – names to assign to the input nodes of the graph, in order.

• output_names (Sequence[str]|None) – names to assign to the output nodes of the graph, in order.

• opset_version (int |None) – The version of thedefault (ai.onnx) opsetto target. You should setopset_version according to the supported opset versionsof the runtime backend or compiler you want to run the exported model with.Leave as default (None) to use the recommended version, or refer tothe ONNX operators documentation for more information.

• dynamo (bool) – Whether to export the model withtorch.export ExportedProgram instead of TorchScript.

• external_data (bool) – Whether to save the model weights as an external data file.This is required for models with large weights that exceed the ONNX file size limit (2GB).When False, the weights are saved in the ONNX file with the model architecture.

• dynamic_shapes (dict[str,Any]|tuple[Any,...]|list[Any]|None) – A dictionary or a tuple of dynamic shapes for the model inputs. Refer totorch.export.export() for more details. This is only used (and preferred) when dynamo is True.Note that dynamic_shapes is designed to be used when the model is exported with dynamo=True, whiledynamic_axes is used when dynamo=False.

• custom_translation_table (dict[Callable,Callable |Sequence[Callable]]|None) – A dictionary of custom decompositions for operators in the model.The dictionary should have the callable target in the fx Node as the key (e.g.torch.ops.aten.stft.default),and the value should be a function that builds that graph using ONNX Script. This optionis only valid when dynamo is True.

• report (bool) – Whether to generate a markdown report for the export process. This optionis only valid when dynamo is True.

• optimize (bool) – Whether to optimize the exported model. This optionis only valid when dynamo is True. Default is True.

• verify (bool) – Whether to verify the exported model using ONNX Runtime. This optionis only valid when dynamo is True.

• profile (bool) – Whether to profile the export process. This optionis only valid when dynamo is True.

• dump_exported_program (bool) – Whether to dump thetorch.export.ExportedProgram to a file.This is useful for debugging the exporter. This option is only valid when dynamo is True.

• artifacts_dir (str |os.PathLike) – The directory to save the debugging artifacts like the report and the serializedexported program. This option is only valid when dynamo is True.

• fallback (bool) – Whether to fallback to the TorchScript exporter if the dynamo exporter fails.This option is only valid when dynamo is True. When fallback is enabled, It isrecommended to set dynamic_axes even when dynamic_shapes is provided.

• export_params (bool) –

  When ``f`` is specified: If false, parameters (weights) will not be exported.

  You can also leave it unspecified and use the returnedtorch.onnx.ONNXProgramto control how initializers are treated when serializing the model.

• keep_initializers_as_inputs (bool) –

  When ``f`` is specified: If True, all theinitializers (typically corresponding to model weights) in theexported graph will also be added as inputs to the graph. If False,then initializers are not added as inputs to the graph, and onlythe user inputs are added as inputs.

  Set this to True if you intend to supply model weights at runtime.Set it to False if the weights are static to allow for better optimizations(e.g. constant folding) by backends/runtimes.

  You can also leave it unspecified and use the returnedtorch.onnx.ONNXProgramto control how initializers are treated when serializing the model.

• dynamic_axes (Mapping[str,Mapping[int,str]]|Mapping[str,Sequence[int]]|None) –

  Prefer specifyingdynamic_shapes whendynamo=True and whenfallbackis not enabled.

  By default the exported model will have the shapes of all input and output tensorsset to exactly match those given inargs. To specify axes of tensors asdynamic (i.e. known only at run-time), setdynamic_axes to a dict with schema:

  • KEY (str): an input or output name. Each name must also be provided ininput_names or

    output_names.

  • VALUE (dict or list): If a dict, keys are axis indices and values are axis names. If a

    list, each element is an axis index.

  For example:

  classSumModule(torch.nn.Module):defforward(self,x):returntorch.sum(x,dim=1)torch.onnx.export(SumModule(),(torch.ones(2,2),),"onnx.pb",input_names=["x"],output_names=["sum"],)

  Produces:

  input{name:"x"...shape{dim{dim_value:2# axis 0}dim{dim_value:2# axis 1...output{name:"sum"...shape{dim{dim_value:2# axis 0...

  While:

  torch.onnx.export(SumModule(),(torch.ones(2,2),),"onnx.pb",input_names=["x"],output_names=["sum"],dynamic_axes={# dict value: manually named axes"x":{0:"my_custom_axis_name"},# list value: automatic names"sum":[0],},)

  Produces:

  input{name:"x"...shape{dim{dim_param:"my_custom_axis_name"# axis 0}dim{dim_value:2# axis 1...output{name:"sum"...shape{dim{dim_param:"sum_dynamic_axes_1"# axis 0...

• training (_C_onnx.TrainingMode) – Deprecated option. Instead, set the training mode of the model before exporting.

• operator_export_type (_C_onnx.OperatorExportTypes) – Deprecated option. Only ONNX is supported.

• do_constant_folding (bool) – Deprecated option.

• custom_opsets (Mapping[str,int]|None) – Deprecated option.

• export_modules_as_functions (bool |Collection[type[torch.nn.Module]]) – Deprecated option.

• autograd_inlining (bool) – Deprecated option.

Returns:

torch.onnx.ONNXProgram if dynamo is True, otherwise None.

Return type:

ONNXProgram | None

Changed in version 2.6:training is now deprecated. Instead, set the training mode of the model before exporting.operator_export_type is now deprecated. Only ONNX is supported.do_constant_folding is now deprecated. It is always enabled.export_modules_as_functions is now deprecated.autograd_inlining is now deprecated.

Changed in version 2.7:optimize is now True by default.

Changed in version 2.9:dynamo is now True by default.

torch.onnx.is_in_onnx_export()[source]

Returns whether it is in the middle of ONNX export.

Return type:

bool

Classes#

classtorch.onnx.ONNXProgram(model,exported_program)

A class to represent an ONNX program that is callable with torch tensors.

Variables:

• model – The ONNX model as an ONNX IR model object.

• exported_program – The exported program that produced the ONNX model.

classtorch.onnx.OnnxExporterError

Errors raised by the ONNX exporter. This is the base class for all exporter errors.

Deprecated APIs#

torch.onnx.register_custom_op_symbolic(symbolic_name,symbolic_fn,opset_version)[source]#

Registers a symbolic function for a custom operator.

When the user registers symbolic for custom/contrib ops,it is highly recommended to add shape inference for that operator via setType API,otherwise the exported graph may have incorrect shape inference in some extreme cases.An example of setType istest_aten_embedding_2 intest_operators.py.

See “Custom Operators” in the module documentation for an example usage.

Parameters:

• symbolic_name (str) – The name of the custom operator in “<domain>::<op>”format.

• symbolic_fn (Callable) – A function that takes in the ONNX graph andthe input arguments to the current operator, and returns newoperator nodes to add to the graph.

• opset_version (int) – The ONNX opset version in which to register.

torch.onnx.unregister_custom_op_symbolic(symbolic_name,opset_version)[source]#

Unregisterssymbolic_name.

See “Custom Operators” in the module documentation for an example usage.

Parameters:

• symbolic_name (str) – The name of the custom operator in “<domain>::<op>”format.

• opset_version (int) – The ONNX opset version in which to unregister.

torch.onnx.select_model_mode_for_export(model,mode)[source]#

A context manager to temporarily set the training mode ofmodeltomode, resetting it when we exit the with-block.

Deprecated since version 2.7:Please set training mode before exporting the model.

Parameters:

• model – Same type and meaning asmodel arg toexport().

• mode (TrainingMode) – Same type and meaning astraining arg toexport().