ONNX external data lets a model keep large tensors in separate files next to the model file, referenced by a relative path. That is convenient for big models, but any format that names files on disk needs careful path handling, so load models from sources you trust.
How external data works
An ONNX model is normally one protobuf file. Large tensors can instead be stored outside it. According to the ONNX documentation, a tensor with external data sets its data location to EXTERNAL, and a list of key value pairs says where the bytes live.
The main keys:
| Key | Meaning |
|---|---|
| location | Required. A file path relative to the directory where the model was stored |
| offset | Optional. Where in the file the tensor starts |
| length | Optional. How many bytes to read |
| checksum | Optional. A SHA1 digest of the referenced file |
The docs say offsets should be multiples of the page size, usually 4kb, to allow memory mapping. They also note that for models over 2GB, you should pass the model file path to the checker, with the external data in the same directory, since passing a loaded model object fails at that size.
Why paths are the security question
Any time a file says "go read this other file," the path becomes an input from the model publisher. A careless loader could be tricked into reading outside the model folder. The ONNX docs address the basics: up directory path components are disallowed and should be stripped when parsing. There is also a separate External Data Security page in the ONNX documentation, which I could not read in full here, so check it for current guidance on symlinks and other cases.
Do not rely on the format alone. Keep your runtime updated, since loader fixes ship in releases, and keep model files out of directories that also hold secrets.
The checksum field, used honestly
The checksum key is a SHA1 digest. It helps you notice accidental corruption. SHA1 is not a modern choice for resisting a determined attacker, so do not treat it as proof the file is the one the publisher intended. Compute your own SHA256 of every file in the model folder and record it.
A short routine for ONNX models
- List every file in the model directory, not only the .onnx file. External data files are part of the model.
- Hash each file with SHA256 and store the list in your inventory.
- Load models from a clean, dedicated folder with no symlinks you did not create.
- Run the loader as a low privilege user, without credentials in the environment.
- Update the runtime on a schedule, and read its release notes for loader fixes.
- Keep the model source and revision in the same record.
Quick check
Is the .onnx file the whole model?
Not always. With external data, large tensors sit in other files. If you only hash or review the .onnx file, you miss part of the model.
Is the SHA1 checksum in ONNX enough for integrity?
It is a useful consistency check, but it is not a strong guard against tampering. Record your own SHA256 digests at the time you approve the model.
Safeguard scans dependencies and generates SBOMs for your repositories, which includes the ML runtimes you install. Try a free scan at gold.safeguard.sh/scan.
Sources
Last reviewed: 19 October 2026.
