Jump to content
Setting up an AI agent? ReverseEngineering.wiki skill (works from the command line, no configuration): https://reverseengineering.wiki/skill/rewiki/SKILL.md · setup for every client, including MCP: https://reverseengineering.wiki/llms.txt · REWiki:Connect

Format:Marshal (Python)

From ReverseEngineering.wiki
Format
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 + int32 returns 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
  • code is a bytes object with the bytecode; consts a tuple holding nested code objects for functions and classes; names the global/attribute names.
  • 3.11+ merges local, cell and free variable names into localsplusnames, with one kind byte each in localspluskinds: 0x20 local, 0x40 cell, 0x80 free, 0x10 hidden, and argument bits (see the CO_FAST_* enum fact).
  • flags: see the CO_* enum fact (0x1 OPTIMIZED ... 0x200 ASYNC_GENERATOR, __future__ flags from 0x20000).
  • linetable (3.11+): location entries whose first byte is 1cccclll (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 and InternalDocs/code_objects.md. 3.10 uses byte pairs (PEP 626, see its fact), 3.9 and older co_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 and InternalDocs/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

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_varint example in CPython's InternalDocs/code_objects.md (main, October 2026) masks off its own continuation bit and returns 08 03 for 200, so do not use it to build test data.
  • A negative int32 count in l means a negative number, not an error.
  • Small ints and other shared constants carry the reference flag too (marshal.dumps(65536) is E9 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.c at commit 010bebbf (main): type codes, r_object, r_ref_reserve, r_PyLong, the TYPE_CODE reader, 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.h and Include/internal/pycore_code.h for the flags and kinds; Doc/library/marshal.rst for the version table.
  • Runtime test: marshal.dumps output 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.