What Is an .ONNX File & How to Open It

ONNX Model (.onnx)

Overview

ONNX (Open Neural Network Exchange) is an open format for representing machine learning models. An .onnx file contains a trained model's computation graph - its operators, their connections, and the learned weights - in a framework-neutral form, so a model trained in PyTorch can run in a C# service, on a mobile device, or inside a browser without the training framework present.

The file is a serialised Protocol Buffers message. That makes it compact, fast to parse, and readable by any language with a protobuf implementation.

Technical Specifications

Format Details

MIME Type: application/octet-stream
File Extensions: .onnx, .ort (ONNX Runtime optimised format)
Category: Data
Serialisation: Protocol Buffers (proto3)
Schema: onnx.proto, defining ModelProto as the root message
Introduced: 2017
Governance: Linux Foundation AI & Data

Identification

ONNX files have no fixed magic number, because protobuf messages start with a field tag rather than a signature. In practice the first bytes usually encode the ir_version field, and the string onnx or a producer name such as pytorch appears early in the file:

head -c 64 model.onnx | xxd
strings model.onnx | head -20

Reliable identification means parsing the protobuf against the ONNX schema rather than matching bytes - a good example of a format where structural validation beats signature matching.

File Structure

The root ModelProto wraps metadata and a single graph:

ModelProto
├── ir_version              ONNX IR version
├── producer_name           "pytorch", "tf2onnx", "skl2onnx", ...
├── producer_version
├── opset_import[]          operator set domains and versions
└── GraphProto
      ├── name
      ├── input[]           ValueInfoProto: name, type, shape
      ├── output[]          ValueInfoProto
      ├── initializer[]     TensorProto: the trained weights
      ├── value_info[]      types for intermediate tensors
      └── node[]            NodeProto: the operators
            ├── op_type     "Conv", "Gemm", "Relu", "MatMul", ...
            ├── input[]     names of incoming tensors
            ├── output[]    names of produced tensors
            └── attribute[] kernel size, strides, epsilon, ...

The graph is a directed acyclic graph connected by tensor names: a node lists the names it consumes and produces, and the runtime resolves those into edges. Weights live in initializer as TensorProto entries, which is where nearly all of a model file's size sits.

Opsets

opset_import pins the version of the operator set the model was written against. Operators evolve - new attributes, changed defaults - and the opset number tells a runtime how to interpret each node. A model exported with opset 17 may fail to load on a runtime that only supports up to opset 13.

History and Development

Microsoft and Facebook announced ONNX in September 2017 to break the lock-in between training frameworks and deployment targets. At the time, moving a model from one framework to another meant a manual reimplementation.

AWS, Nvidia, Intel, AMD, and others joined quickly, and in 2019 the project moved to the Linux Foundation. The specification expanded from inference-only graphs to cover training (ONNX Training) and quantised models.

ONNX Runtime, Microsoft's inference engine, became the reference implementation and is now the usual way ONNX models are executed in production, with hardware backends for CUDA, TensorRT, DirectML, CoreML, and OpenVINO.

Common Use Cases

Cross-framework deployment: training in PyTorch, serving without a PyTorch dependency.
Edge and mobile inference: running models on devices where the training framework is too heavy.
Hardware acceleration: targeting vendor runtimes that consume ONNX natively.
Browser inference: ONNX Runtime Web executes models via WebAssembly and WebGPU.
Model archival: storing a portable, framework-independent record of a trained model.
Language-agnostic serving: loading models from C#, Java, Rust, or Go services.

How to Open an ONNX File

Visual inspection

Netron: the standard tool. A desktop app and web viewer (netron.app) that renders the graph node by node, showing shapes, attributes, and weight tensors. Open the file and the architecture is immediately legible.

In Python

import onnx

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

# Validate structure and opset consistency
onnx.checker.check_model(model)

print("IR version:", model.ir_version)
print("Producer:", model.producer_name, model.producer_version)
print("Opsets:", [(o.domain or "ai.onnx", o.version) for o in model.opset_import])

# Inputs and their shapes
for inp in model.graph.input:
    dims = [d.dim_value or d.dim_param for d in inp.type.tensor_type.shape.dim]
    print("input:", inp.name, dims)

# A readable dump of the whole graph
print(onnx.helper.printable_graph(model.graph))

Running inference

import numpy as np
import onnxruntime as ort

session = ort.InferenceSession("model.onnx", providers=["CPUExecutionProvider"])

input_name = session.get_inputs()[0].name
dummy = np.random.rand(1, 3, 224, 224).astype(np.float32)

outputs = session.run(None, {input_name: dummy})
print(outputs[0].shape)

Exporting to ONNX

import torch

model.eval()
dummy = torch.randn(1, 3, 224, 224)

torch.onnx.export(
    model, dummy, "model.onnx",
    input_names=["input"], output_names=["logits"],
    dynamic_axes={"input": {0: "batch"}, "logits": {0: "batch"}},
    opset_version=17,
)

From other frameworks: tf2onnx for TensorFlow, skl2onnx for scikit-learn, and onnxmltools for XGBoost and LightGBM.

Security Considerations

An ONNX file is data, not code, which makes it safer than a pickle checkpoint. It is not risk-free, though: malformed protobuf can trigger parser bugs, very large declared tensor shapes can exhaust memory, and custom operators may load external shared libraries. Validate with onnx.checker and run untrusted models in a sandbox.

Advantages

Framework-independent: decouples training from deployment.
Broad hardware support: vendor runtimes consume ONNX directly.
Compact and fast to load: protobuf parsing with weights stored as raw tensors.
Inspectable: the graph is fully introspectable, and Netron makes it visual.
Safer than pickle: declarative data rather than executable code.
Open governance: a Linux Foundation project with a published specification.

Limitations

Operator coverage gaps: exotic or custom layers may have no ONNX equivalent, and export fails or produces an unsupported custom op.
Opset friction: version mismatches between exporter and runtime are a common source of load failures.
Dynamic control flow is awkward: models with data-dependent branching or loops export poorly.
Numerical drift: small differences between the original framework and the runtime can appear, especially after quantisation.
2 GB protobuf limit: models above it must store weights in external data files alongside the .onnx.

PYTORCH: PyTorch's native checkpoint format.
PROTOBUF: the serialisation ONNX is built on.
PROTO: the schema language defining ONNX's message types.
H5: HDF5, historically used for Keras model weights.
PICKLE: the Python serialisation ONNX avoids for portability and safety.

What Is an .ONNX File?