Format:PyTorch model archive
| Developer | PyTorch |
|---|---|
| Magic | PK (ZIP) |
| Extensions | .pt, .pth, .bin, .ptl |
| License | BSD-3-Clause |
| On this wiki | Facts · Code · Notes · Topics |
PyTorch .pt/.pth/.ptl files saved by torch.save or torch.jit.save since 1.6: a ZIP with a pickled data.pkl, raw tensor storages under data/, and version and byteorder records; TorchScript adds code/ and constants.
Layout
The writer/reader in caffe2/serialize/inline_container.cc (PyTorchStreamReader) opens the file as a ZIP (miniz). The first entry's name gives the archive folder, and every record is looked up under that folder prefix, so entries look like <name>/data.pkl, <name>/version, <name>/byteorder, <name>/data/0, <name>/data/1... Seen in the source: records named .data/version or version (the format version as text), byteorder ("little" or "big", written if missing) and a serialization id record. Unverified: data.pkl holds the pickled object graph that refers to storages by key; TorchScript archives also contain code/*.py and constants.pkl.
The reader rejects files that begin with the 8 bytes PYTORCH1, the legacy preview-release format ("File is an unsupported archive format from the preview release"). Older torch.save files (before 1.6) are not ZIP but a pickle stream.
Versions
versions.h in the same directory sets kMinSupportedFileFormatVersion = 1 and kProducedFileFormatVersion = 0xA (10), bumped when operator semantics change (comments list aten::div, aten::full, linspace, logspace, gelu).
Security
A pickle can run code when loaded: never torch.load an untrusted file without weights_only; prefer Format:safetensors. Parse data.pkl with a restricted unpickler.
See Technique:Identifying machine-learning models in applications. Related: Format:APK (ZIP).
Legacy and loading
torch/serialization.py (pytorch 6a6db44) shows three things not stated above. (1) The zip writer stores the pickled object graph as record data.pkl, a byteorder record holding sys.byteorder ("little" or "big"; optional, a flag can disable it), and each tensor storage as data/<key> where key is the persistent id used inside the pickle (lines 1260-1281); the reader extracts data.pkl with get_record and resolves the storage keys through a pickle persistent_load hook. TorchScript archives are told apart by _is_torchscript_zip. (2) The old pre-1.6 torch.save format (still writable with the legacy flag) is not a zip but a plain stream of pickles: pickle of MAGIC_NUMBER 0x1950A86A20F9469CFC6C, pickle of PROTOCOL_VERSION 1001, pickle of a sys_info dict (protocol_version, little_endian, type_sizes short/int/long), then the pickled object with persistent ids (lines 65-66, 1150-1170; Unverified: the raw storage bytes follow the object pickle); loaders check both numbers and report a mismatch. (3) The zip check is exact: _is_zipfile reads the first 4 bytes and requires PK\x03\x04 (lines 429-442). torch.load now defaults to weights_only=True (signature at line 1330), which restricts unpickling to an allowlist; the env vars TORCH_FORCE_WEIGHTS_ONLY_LOAD and TORCH_FORCE_NO_WEIGHTS_ONLY_LOAD override it (lines 1495-1500). That default does not make arbitrary .pt files safe to treat as trusted: parse data.pkl with your own restricted unpickler when in doubt.
See also
- Format:ZIP (container) and Format:Python pickle (data.pkl opcodes, why loading runs code)
Code & repositories
- https://github.com/pytorch/pytorch @
6a6db44e15f9678d573ad0af5e1f3e2b0713414a· license: BSD-3-Clause (read from LICENSE; GitHub's API was busy)
caffe2/serialize: PyTorchStreamReader/Writer of the zip archive
Tested on: source read, not run: read source · checked 2026-10-18