.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, and the number goes up by one for each change within that 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.

The final number of each release is below; 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. The explorer turns it down. py_compile and compileall make hash-based files with their invalidation mode options.

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.

Examples

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.

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. Numbers marked final are those of a released version. Other numbers come from alphas, betas and release candidates, and the release shown is the pre-release that introduced them.