Format:Python pickle
| Vendor | Python Software Foundation |
|---|---|
| Magic | 80 02 .. 80 05 (protocol 2-5); protocol 0/1 have none |
| Extensions | .pkl, .pickle, .pt, .joblib |
| License | PSF |
| On this wiki | Facts · Code · Notes · Topics |
Python's object serialization: a stack-machine bytecode ending in STOP '.', protocols 0-5 (protocol 2+ starts with PROTO 0x80 plus version byte); loading runs arbitrary callables through GLOBAL/STACK_GLOBAL and REDUCE.
Overview
A pickle is a program for a small stack machine with a memo (id to object). Each opcode is one byte, mostly followed by an argument. The stream ends with STOP '.' (0x2e). The unpickler resolves a class or function by name (module, qualname) and calls it, which is why unpickling untrusted data executes code: GLOBAL ('c' module\nname\n) or STACK_GLOBAL (0x93, name from the stack) pushes any importable callable, and REDUCE ('R') calls it with a tuple (os.system, builtins.eval, subprocess.Popen...). BUILD and NEWOBJ also invoke methods. Hence ML model files stored as pickles (Format:PyTorch model archive, joblib, sklearn) can carry payloads; scan the GLOBAL/STACK_GLOBAL names without loading.
Protocols
0 ASCII (default before 3.0); 1 binary; 2 (Python 2.3, PROTO opcode, new-style classes); 3 (Python 3.0, bytes); 4 (3.4, FRAME, MEMOIZE, STACK_GLOBAL, large objects, sets); 5 (3.8, out-of-band buffers). Python 3.8-3.13 default is 4. A protocol >=2 stream starts 80 <protocol>; protocol 4+ typically follows with FRAME 0x95 and an 8-byte frame length.
Opcode table (code: name, protocol introduced)
Integers/floats: 'I' INT 0; 'J' BININT 1; 'K' BININT1 1; 'M' BININT2 1; 'L' LONG 0; 0x8a LONG1 2; 0x8b LONG4 2; 'F' FLOAT 0; 'G' BINFLOAT 1. Strings/bytes: 'S' STRING 0; 'T' BINSTRING 1; 'U' SHORT_BINSTRING 1; 'V' UNICODE 0; 'X' BINUNICODE 1; 0x8c SHORT_BINUNICODE 4; 0x8d BINUNICODE8 4; 'B' BINBYTES 3; 'C' SHORT_BINBYTES 3; 0x8e BINBYTES8 4; 0x96 BYTEARRAY8 5; 0x97 NEXT_BUFFER 5; 0x98 READONLY_BUFFER 5. Constants: 'N' NONE; 0x88 NEWTRUE 2; 0x89 NEWFALSE 2. Containers: ']' EMPTY_LIST 1; 'a' APPEND; 'e' APPENDS 1; 'l' LIST; ')' EMPTY_TUPLE 1; 't' TUPLE; 0x85/0x86/0x87 TUPLE1/2/3 (2); '}' EMPTY_DICT 1; 'd' DICT; 's' SETITEM; 'u' SETITEMS 1; 0x8f EMPTY_SET 4; 0x90 ADDITEMS 4; 0x91 FROZENSET 4. Stack/memo: '0' POP; '2' DUP; '(' MARK; '1' POP_MARK 1; 'g' GET; 'h' BINGET 1; 'j' LONG_BINGET 1; 'p' PUT; 'q' BINPUT 1; 'r' LONG_BINPUT 1; 0x94 MEMOIZE 4. Objects/code paths: 'c' GLOBAL; 0x93 STACK_GLOBAL 4; 'R' REDUCE; 'b' BUILD; 'i' INST; 'o' OBJ 1; 0x81 NEWOBJ 2; 0x92 NEWOBJ_EX 4; 0x82/0x83/0x84 EXT1/2/4 (2, copyreg extension registry). Control: 0x80 PROTO 2; '.' STOP; 0x95 FRAME 4; 'P' PERSID; 'Q' BINPERSID 1 (persistent ids; PyTorch uses them to point at tensor storages).
Analysis
Use python -m pickletools file.pkl (disassembler, safe: it does not execute) to read a pickle; pickletools.genops yields opcodes. Look at every GLOBAL/STACK_GLOBAL: legitimate model files reference torch._utils._rebuild_tensor_v2, collections.OrderedDict, numpy core multiarray reconstruct; anything importing os, posix, subprocess, builtins eval/exec, socket is hostile. Safer loaders: torch.load(weights_only=True) and Format:Safetensors.
Sources
https://github.com/python/cpython Lib/pickletools.py (opcode names, codes and protocol numbers read from the I(name=..., code=..., proto=...) table). The default-protocol history and the exploit explanation are from general knowledge of pickle.py and not re-read here (Unverified).
Code & repositories
- https://github.com/python/cpython @
7dbc7975db8e34db8be8e4a10bd10784ab49b07a· license: PSF-2.0 (declared by the contributor; GitHub's detector did not recognize LICENSE)
Lib/pickletools.py: opcode table and disassembler
Tested on: source read, not run: read pickletools.py · checked 2026-10-18; last activity 2026-10-18
See also
Format:ZIP, Format:PyTorch model archive, Format:Safetensors
Compare Format:Ruby Marshal and Format:NRBF (.NET BinaryFormatter stream); many game saves use one of them (Technique:Reverse engineering game save files).