Implementation:Onnx Onnx Convert Model To External Data

Knowledge Sources	ONNX ONNX External Data
Domains	External_Data, Large_Model_Support
Last Updated	2026-02-10 00:00 GMT

Overview

Concrete tool for marking ONNX model tensors for external data storage provided by the ONNX external_data_helper module.

Description

The convert_model_to_external_data function iterates over model tensors and marks those with raw data at or above the size threshold for external storage. It sets each qualifying tensor's data_location to EXTERNAL and populates external_data entries with the target file location. The function modifies the model in-place. When all_tensors_to_one_file=True (default), all tensors reference the same external file; when False, each tensor gets its own file named after the tensor.

Usage

Import this function when you need fine-grained control over external data conversion. For simple use cases, save_model(save_as_external_data=True) calls this function automatically. Use this directly when you need to customize the conversion before saving.

Code Reference

Source Location

Repository: onnx
File: onnx/external_data_helper.py
Lines: 114-169

Signature

def convert_model_to_external_data(
    model: ModelProto,
    all_tensors_to_one_file: bool = True,
    location: str | None = None,
    size_threshold: int = 1024,
    convert_attribute: bool = False,
) -> None:
    """Mark tensors with raw data as external data.

    Args:
        model: Model to convert (modified in-place).
        all_tensors_to_one_file: Save all tensors to one file (default: True).
        location: External file name, relative to model path.
            Auto-generated UUID if None.
        size_threshold: Minimum tensor size in bytes to externalize (default: 1024).
            Set to 0 to externalize all tensors.
        convert_attribute: Also convert attribute tensors (default: False).

    Raises:
        ValueError: If location is an absolute path.
        FileExistsError: If a file already exists at the location.
    """

Import

from onnx.external_data_helper import convert_model_to_external_data

I/O Contract

Inputs

Name	Type	Required	Description
model	ModelProto	Yes	Model to convert (modified in-place)
all_tensors_to_one_file	bool	No	Single file for all tensors (default: True)
location	str or None	No	External file name (auto-generated if None)
size_threshold	int	No	Minimum tensor size to externalize in bytes (default: 1024)
convert_attribute	bool	No	Also externalize attribute tensors (default: False)

Outputs

Name	Type	Description
return	None	Model modified in-place with external data markers

Usage Examples

Basic Conversion

import onnx
from onnx.external_data_helper import convert_model_to_external_data

model = onnx.load_model("model.onnx")

# Mark all tensors >= 1KB for external storage
convert_model_to_external_data(
    model,
    all_tensors_to_one_file=True,
    location="weights.bin",
    size_threshold=1024,
)

Per-tensor Files

from onnx.external_data_helper import convert_model_to_external_data

# Each tensor gets its own external file
convert_model_to_external_data(
    model,
    all_tensors_to_one_file=False,
    size_threshold=0,  # externalize ALL tensors
)

Related Pages

Implements Principle

Principle:Onnx_Onnx_External_Data_Conversion

Requires Environment

Environment:Onnx_Onnx_Python_Runtime_Environment

Uses Heuristic

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment