Compare
Safetensors vs ONNX: weights or model graphs
Safetensors stores named tensors. ONNX represents a model with a computation graph, inputs, outputs, and operator versions.
Which format should you choose?
Consider Safetensors to load weights into a compatible model, or ONNX to deliver a graph to a compatible runtime.
Good fit for Safetensors
Storing and distributing machine-learning tensor weights · Loading weights across supported frameworks
- Exchanging tensors and basic metadata rather than arbitrary Python objects
- Workflows that inspect and load selected tensors
Good fit for ONNX
Exchanging machine-learning computation graphs and weights with supported runtimes · Moving models between training frameworks and inference environments
- Inference with runtimes that support the model's operators and opset
- Exchanging a model graph with inputs outputs and types
Basic information
| Field | Safetensors | ONNX |
|---|---|---|
| Extension | .safetensors | .onnx |
| MIME type | application/octet-stream | application/octet-stream |
| Common uses | Storing and distributing machine-learning tensor weights · Loading weights across supported frameworks | Exchanging machine-learning computation graphs and weights with supported runtimes · Moving models between training frameworks and inference environments |
| How to open | Use a Safetensors-compatible library or model tool. Supported tools can inspect tensor names, dtypes, and shapes before loading all weights to a device. The JSON header does not make the entire file a JSON text document. | Load it with an ONNX checker or compatible inference runtime. Before deployment, inspect IR and opset versions, operators, input/output types and shapes, and runtime support; compare outputs with the source model on representative inputs. |
| Export or convert | Save tensor weights through an API supported by the model framework. Converting from a pickle-based input may deserialize that input, so do not load an untrusted source casually. Compare tensor names, shapes, dtypes, element counts, and model outputs after conversion. | Export using the source framework's ONNX exporter and validate the structure with an ONNX checker. Successful conversion does not guarantee numerical equivalence or execution on the target device. If external data is used, keep the model and every referenced file together in the distribution unit. |
Choose by use case
Exchanging tensors and basic metadata rather than arbitrary Python objects
Storing and distributing machine-learning tensor weights · Loading weights across supported frameworks
SafetensorsWorkflows that inspect and load selected tensors
Storing and distributing machine-learning tensor weights · Loading weights across supported frameworks
SafetensorsInference with runtimes that support the model's operators and opset
Exchanging machine-learning computation graphs and weights with supported runtimes · Moving models between training frameworks and inference environments
ONNXExchanging a model graph with inputs outputs and types
Exchanging machine-learning computation graphs and weights with supported runtimes · Moving models between training frameworks and inference environments
ONNXKey point 1
Safetensors alone does not define model architecture or inference code.
More on the differencesKey point 2
ONNX can contain graph initializer tensors and reference external data.
More on the differencesMore on the differences
These are not direct substitutes. Creating ONNX from weights requires a model definition and a supported export process. Renaming an extension does not create a graph.
- The Safetensors header records tensor names, dtype, shape, and data ranges. Check separately for shard indexes, configuration, tokenizers, and other requirements.
- Check ONNX IR/opset, operators, and types against the runtime, and preserve external weight references. Compare outputs using identical preprocessing and representative inputs; structural checks do not guarantee accuracy or speed.
Frequently asked questions
Can Safetensors be trusted regardless of its source?
No. It avoids pickle-based arbitrary object reconstruction, but does not guarantee source, loader, dependency code, or model safety.