.PYC File Format – Header

Magic number

The first two bytes are a 16-bit number, and the next two are always 0D 0A, a carriage return and a line feed. A file copied in text mode has those bytes changed, so the magic number no longer matches and the file is rejected.

CPython changes the number whenever the bytecode changes in a way an older interpreter cannot run. Python 3.n starts at 2900 + 50n, so 3.15 starts at 3650, and the number goes up by one for each change during its development. A file loads only on a release with exactly the same number. The file does not say which release it came from in any other way.

The numbers of the pre-releases are listed further down.

Flags

A 32-bit field that says how the file is checked against its source. Two bits are defined by PEP 552, and CPython rejects a file with any other bit set.

The value 2, bit 1 alone, is never written. CPython’s importer would read such a file as one checked by date and size, since bit 0 is clear; the explorer turns it down. py_compile and compileall make hash-based files with their invalidation mode options. The interpreter’s --check-hash-based-pycs option (default, always or never) can override the check when a hash-based file is loaded.

source_mtime

Unsigned 32-bit, at offset 8, when flags is 0. The source file’s modification time in seconds since 1970, as a Unix timestamp, kept to 32 bits. A file is stale if this differs from the source file’s current time.

source_size

Unsigned 32-bit, at offset 12, when flags is 0. The size of the source file in bytes, modulo 2³². A file is stale if this differs from the source’s current size.

source_hash

8 bytes at offset 8, when bit 0 of flags is set. A 64-bit SipHash-1-3 of the source file’s bytes, keyed by the magic number’s four bytes read as a little-endian number, 0x0A0D0E52. importlib.util.source_hash() computes it. Python’s importer does not recompute it when flags is 1, unless --check-hash-based-pycs always is given.

Examples

Both examples are for the same six-byte source, x = 1 and a line feed. They were constructed by hand from the rules above, with no Python 3.15 interpreter to check against. The hash was computed with the same SipHash-1-3 function and the 3.15 key.

00000000  52 0E 0D 0A 00 00 00 00 00 F1 53 65 06 00 00 00

00000000  52 0E 0D 0A 03 00 00 00 A8 AB DB 6F 34 C4 41 FD

File names and folders

importlib stores a module’s compiled form in a __pycache__ folder beside the source, named with the interpreter’s tag, as PEP 3147 describes. The tag gives the release, so several versions of Python can share one source folder. The tag of Python 3.15 is cpython-315.

A spam.pyc file with no spam.py beside it is loaded as a module that has no source. The .pyo extension is not used in this format.

All magic numbers

The list is the one in CPython’s own source, Include/internal/pycore_magic_number.h. Only 3666 is the number of a released version. The others come from alphas and betas, and the release shown is the pre-release that introduced them.