A safetensors file has three parts: an 8 byte number giving the header size, a JSON header describing each tensor, and one block of raw tensor bytes. There is no code in it. A loader reads the header, then reads byte ranges, which is why the format is safer than pickle.
The layout, step by step
The safetensors project describes the file this way:
- The first 8 bytes hold N, an unsigned 64 bit integer in little endian order, giving the size of the header.
- The next N bytes are a UTF-8 JSON header. It must start with an opening brace, and it may be padded with trailing spaces.
- The header maps each tensor name to its dtype, its shape and its data_offsets, which are positions relative to the start of the byte buffer.
- An optional key named
__metadata__can hold string to string pairs, and nothing else. - The rest of the file is the raw byte buffer.
That is the whole format. A reader never executes anything from the file. It parses JSON and slices bytes.
Checks that come with the design
The project README lists several properties that make hostile files harder to use:
| Property | What the README says |
|---|---|
| No code execution | Pickle is marked unsafe because it runs arbitrary code; safetensors holds tensor data only |
| Header size limit | A 100MB limit on the header guards against denial of service |
| No overlapping ranges | Address ranges cannot overlap |
| No holes | The byte buffer must be fully indexed, which blocks polyglot files |
The no holes rule is easy to miss. If every byte must belong to a declared tensor, an attacker cannot tuck a second payload into unused space in the same file.
Lazy loading
Because the header gives exact offsets, a loader can read only the tensors it needs. The README says this helps in distributed setups, and cites loading a large model onto 8 GPUs dropping from about 10 minutes to about 45 seconds. That is a speed benefit, not a security one, but it is why teams adopt the format willingly.
What the metadata block is for
The optional __metadata__ section is free text pairs. It is useful for noting a framework name or a format version. Treat it as a label written by whoever made the file. It is not verified, so do not use it as proof of origin.
What the format does not promise
The README is direct about one gap: tensor values are not checked, so NaN and Inf values may be present. More broadly, safe to parse does not mean safe to trust. A safetensors file can still hold weights that were trained on bad data or tampered with to change model behavior. The format closes the code execution path. It does not close the provenance question.
So pair it with the other controls:
- Record where the file came from and its digest.
- Pin the exact revision you tested.
- Check the model card for license and training data notes.
- Test outputs against your own evaluation set before production.
Quick check
Can a safetensors file run code when loaded?
The format has no code in it, only a JSON header and raw bytes. The loader parses and slices. Any risk comes from other files in the repo, such as custom model code, not from the weights file.
Does safetensors prove a model is trustworthy?
No. It removes the pickle style code execution path. Weight values, training data and origin still need checking.
Safeguard scans dependencies and generates SBOMs for your repositories, and you can try a free scan at gold.safeguard.sh/scan. For file format comparisons, see safetensors vs pickle vs GGUF.
Sources
Last reviewed: 19 October 2026.
