Every .pyc file of this format starts with the same 16 bytes of header,
all little-endian. The header says which release wrote the file and how to tell whether
it is out of date. The module’s code object follows at offset 16.
0magic: the number, then0D 0A4 bytes4flags4 bytes8source_mtime, or the first half of source_hash4 bytes12source_size, or the second half of source_hash4 bytes
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.
Python 3.10’s final number is 3439, stored as 6F 0D 0D 0A. 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.
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.
| Bit | Meaning |
|---|---|
| 0 | Set: the next 8 bytes are a hash of the source. Clear: they are the source’s date and size. |
| 1 | Only with bit 0: the hash is checked against the source when the file is loaded. |
| Value | Kind of file |
|---|---|
| 0 | Checked by the source’s date and size. The usual kind. |
| 1 | Hash-based, not checked when loaded. The file is used even if the source has changed. |
| 3 | Hash-based, checked when loaded. The source is hashed and the file is used only if the hash matches. |
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 232. 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 6F 0D 0D 0A 00 00 00 00 00 F1 53 65 06 00 00 000x6553F100 (1700000000, 14 November 2023), source size 6 bytes00000000 6F 0D 0D 0A 03 00 00 00 D9 4A AD E2 8C 8C BE BFFile 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.
| Source | Compiled |
|---|---|
spam.py, no optimisation | __pycache__/spam.cpython-310.pyc |
spam.py with -O | __pycache__/spam.cpython-310.opt-1.pyc |
spam.py with -OO | __pycache__/spam.cpython-310.opt-2.pyc |
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. Only 3439 is a final number; the others came from alphas and betas.
| Magic | Release | What changed |
|---|---|---|
| 3430 | 3.10a1 | Make annotations a future feature by default |
| 3431 | 3.10a1 | New line number table format, PEP 626 |
| 3432 | 3.10a2 | Function annotation for MAKE_FUNCTION changed from a dictionary to a tuple |
| 3433 | 3.10a2 | RERAISE restores f_lasti if its argument is nonzero |
| 3434 | 3.10a6 | PEP 634: structural pattern matching |
| 3435 | 3.10a7 | Use instruction offsets, as opposed to byte offsets |
| 3436 | 3.10b1 | Add GEN_START |
| 3437 | 3.10b1 | Undo making annotations a future feature by default |
| 3438 | 3.10b1 | Safer line number table handling |
| 3439 | 3.10b1, final | Add ROT_N |