.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.14 starts at 3600, 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 of the source file’s bytes, keyed by the magic number’s four bytes read as a little-endian number. 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 Python 3.14 compiling the same six-byte source, x = 1 and a line feed.

00000000  2B 0E 0D 0A 00 00 00 00 00 F1 53 65 06 00 00 00

00000000  2B 0E 0D 0A 03 00 00 00 1D B2 B6 32 5C A2 82 A7

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.14 is cpython-314.

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 3627 is the number of a released version. The others come from alphas, betas and release candidates, and the release shown is the pre-release that introduced them.