Format:Marshal (Python)
| Developer | Python Software Foundation (CPython) |
|---|---|
| Versions | marshal format 0-6: 4 is the default from 3.4 to 3.13, 5 in 3.14 (slices), 6 in 3.15 (frozendict) |
| Magic | none (first byte is a type code; a 3.4+ code object starts with E3) |
| Endianness | little |
| License | CPython: PSF-2.0 |
| Website | https://docs.python.org/3/library/marshal.html |
| On this wiki | Facts · Code · Notes · Topics |
CPython's internal serialisation format (the `marshal` module), used for the code objects in Format:PYC (Python compiled bytecode) files and for frozen modules. Each object is a one-byte type code (bit 7 = add the object to the reference table) followed by its payload; integers are little endian, there is no header, magic or length. Format versions 0-6; the code object layout changes with every minor Python version.
Identification
No magic number. A stream normally starts with a code object: E3 ('c' | 0x80) from 3.4, 63 ('c') before. In 3.11+ the next 20 bytes are five int32 (argcount, posonlyargcount, kwonlyargcount, stacksize, flags) followed by F3 or 73 (the bytecode as a bytes object). Inside pycs it follows the Format:PYC (Python compiled bytecode) header.
Type codes
One byte: the low 7 bits are an ASCII type code, bit 7 (FLAG_REF, 0x80) asks the reader to remember the object (see #References). All lengths and counts are int32 little endian unless noted.
| Code | Type | Payload |
|---|---|---|
0 |
NULL | none; ends a dict |
N F T S . |
None, False, True, StopIteration, Ellipsis | none |
i |
int (fits 32 bits) | int32
|
l |
int (long) | int32 n: sign = sign of the number, abs(n) = count of 15-bit digits; then abs(n) uint16 digits, least significant first
|
I |
int64 | int64 (read only, never written now)
|
g / y |
float / complex | 8 / 16 bytes IEEE 754 double LE (version 2+) |
f / x |
float / complex | uint8 length + ASCII repr (version 0-1)
|
s |
bytes | length + bytes |
u / t |
str / interned str | length + UTF-8 (surrogatepass)
|
a / A |
ASCII str / interned | length + bytes (version 4+) |
z / Z |
short ASCII str / interned | uint8 length + bytes (version 4+)
|
( / ) |
tuple / small tuple | count (): uint8) then items
|
[ |
list | count then items |
{ / } |
dict / frozendict (6+) | key, value pairs until a 0 byte
|
< / > |
set / frozenset | count then items |
: |
slice (5+) | start, stop, step objects |
c |
code | see #Code objects |
r |
reference | int32 index into the reference table
|
? |
unknown | writer error marker, never valid input |
Python 2 differs: t is an interned byte string added to a separate list and R + int32 refers back into it; s is the Python 2 str, u unicode.
References
- Version 3+ (Python 3.4+). When the type byte has bit 7 set, the reader appends the object to its reference list. The slot is taken when the type byte is read, before any child objects, so indices follow pre-order: a tuple flagged before its items gets the lower index.
r+int32returns that object again (shared constants, names, interned strings). - Writers up to at least 3.15 set the flag on every object whose reference count is above 1 at write time, so many flagged objects are never referred to, and the flag pattern depends on interpreter state, not on the data. CPython main (3.16 development, October 2026) rewrites the flags afterwards so only objects that are really referred to again carry one. A reader must count every flagged object either way.
Code objects
After c: int32 fields, objects, int32 firstlineno, objects:
| Python | Fields in order |
|---|---|
| 2.x | argcount, nlocals, stacksize, flags; code, consts, names, varnames, freevars, cellvars, filename, name; firstlineno; lnotab |
| 3.0-3.7 | argcount, kwonlyargcount, nlocals, stacksize, flags; code ... name as 2.x; firstlineno; lnotab |
| 3.8-3.10 | argcount, posonlyargcount, kwonlyargcount, nlocals, stacksize, flags; code ... name; firstlineno; lnotab (3.10: linetable) |
| 3.11+ | argcount, posonlyargcount, kwonlyargcount, stacksize, flags; code, consts, names, localsplusnames, localspluskinds, filename, name, qualname; firstlineno; linetable, exceptiontable |
codeis a bytes object with the bytecode;constsa tuple holding nested code objects for functions and classes;namesthe global/attribute names.- 3.11+ merges local, cell and free variable names into
localsplusnames, with one kind byte each inlocalspluskinds: 0x20 local, 0x40 cell, 0x80 free, 0x10 hidden, and argument bits (see theCO_FAST_*enum fact). flags: see theCO_*enum fact (0x1 OPTIMIZED ... 0x200 ASYNC_GENERATOR,__future__flags from 0x20000).linetable(3.11+): location entries whose first byte is1cccclll(code, length - 1 in code units); codes 0-9 short form, 10-12 one-line form, 13 no columns, 14 long form (columns stored + 1), 15 no location. Its varints are 6-bit chunks, least significant first. See the location table fact andInternalDocs/code_objects.md. 3.10 uses byte pairs (PEP 626, see its fact), 3.9 and olderco_lnotab.exceptiontable(3.11+): entries of four varints start, size, target, (depth << 1) | lasti in code units, bit 7 marking an entry's first byte, and here the varints are most significant chunk first. See the exception table fact andInternalDocs/exception_handling.md.- Code:Marshal (Python)/codetables (Python) decodes both from raw bytes.
Versions
| Version | Since | Adds |
|---|---|---|
| 0 | original | |
| 1 | 2.4 | interned strings shared |
| 2 | 2.5 | binary floats g, y
|
| 3 | 3.4 | references (FLAG_REF, r)
|
| 4 | 3.4 | a, A, z, Z, )
|
| 5 | 3.14 | slices :
|
| 6 | 3.15 | frozendict }
|
The format version does not say which Python wrote a code object: 3.4 to 3.13 all write version 4 with different code layouts.
Tools that read/write it
marshal.loads/dumpsof the same Python version (allow_codesince 3.13).- Code:PYC (Python compiled bytecode)/pycinspect (Python) walks marshal streams of any version, with or without a pyc header (
--raw).
Code & repositories
- https://github.com/python/cpython @
010bebbf9fd12bba1e3f40bdbddacd51a9c2bf20· license: PSF-2.0 (declared: the detector found none; check the repository)
CPython, the reference implementation that defines both formats: Include/internal/pycore_magic_number.h (magic number history), Lib/importlib/_bootstrap_external.py (pyc header read/write), Python/marshal.c (marshal reader and writer), Lib/_opcode_metadata.py / Lib/opcode.py (opcode tables per version).
Tested on: Read at main 010bebbf (October 2026) plus the 3.13, 3.14 and 3.15 branches and tags v2.7.18-v3.11.0; claims checked with CPython 3.11.15 and 3.12.8 builds on Windows x64 · checked 2026-10-17; last activity 2026-10-17
Pitfalls
- The format is undocumented on purpose and may change in any version; the code object layout is tied to the interpreter, so pick the parser by Python version, not by marshal version.
- Dicts have no count: read pairs until a key of type
0. - The location table and the exception table use opposite varint chunk orders (least vs most significant first); a shared varint reader decodes one of them wrong without failing. The
encode_varintexample in CPython'sInternalDocs/code_objects.md(main, October 2026) masks off its own continuation bit and returns08 03for 200, so do not use it to build test data. - A negative
int32count inlmeans a negative number, not an error. - Small ints and other shared constants carry the reference flag too (
marshal.dumps(65536)isE9 00 00 01 00), so do not match type bytes without masking bit 7. - The reader limits nesting depth (1000 on Windows builds, 2000 elsewhere in current main).
Evidence & references
- CPython
Python/marshal.cat commit 010bebbf (main): type codes,r_object,r_ref_reserve,r_PyLong, theTYPE_CODEreader,w_ref,w_resolve_refs; tags v2.7.18, v3.7.0, v3.8.0, v3.10.0 and v3.11.0 for the older code object layouts;Include/cpython/code.handInclude/internal/pycore_code.hfor the flags and kinds;Doc/library/marshal.rstfor the version table. - Runtime test:
marshal.dumpsoutput of CPython 3.11.15 and 3.12.8 for versions 0-5, and every stdlib pyc of both versions read by an independent reader.