.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.12 starts at 3500, and the number goes up by one for each change within the release. 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.

Every final Python 3.12 release writes 3531, the bytes CB 0D 0D 0A. The numbers 3500 to 3530 come from the alphas and the first beta; the full list follows 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. 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 files were written by Python 3.12 with py_compile, from a six-byte source file, x = 1 and a line feed.

00000000  CB 0D 0D 0A 00 00 00 00 00 F1 53 65 06 00 00 00

00000000  CB 0D 0D 0A 03 00 00 00 15 22 56 19 17 F5 DF 08

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.

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 kept in Python 3.12’s own source, in the comments of Lib/importlib/_bootstrap_external.py. The number marked final is the one every released 3.12 version writes. The others come from alphas and the first beta, and the release shown is the pre-release that introduced them.