The header is 12 bytes and all its numbers are little-endian. It says which bytecode the file holds and records the date and size of the source file. The code object starts at offset 12.
| Offset | Size | Field | Meaning |
|---|---|---|---|
| 0 | 2 | magic | Which bytecode the file holds |
| 2 | 2 | 0D 0A | A carriage return and a line feed |
| 4 | 4 | source_mtime | The source’s modification time |
| 8 | 4 | source_size | The source’s size in bytes |
Files with magic 3190 or 3200, from the first 3.3 alpha, have no
source_size: the header is 8 bytes and the code object starts at offset
8.
Magic number
A 16-bit number, then the bytes 0D 0A. CPython changes the number
whenever its bytecode changes, and only loads a file whose number is its own. The
carriage return and line feed mean that a file copied in text mode, which alters line
endings, no longer has the right magic number.
The final number of each release is shown in bold; the others belong to alpha, beta and release-candidate builds. 3.5 has two: 3350 up to 3.5.1 and 3351 from 3.5.2. The descriptions are those of the list in CPython’s source.
| Magic | Bytes | Release | What changed |
|---|---|---|---|
| 3190 | 76 0C | 3.3a1 | The __class__ super closure changed |
| 3200 | 80 0C | 3.3a1 | PEP 3155 __qualname__ added |
| 3210 | 8A 0C | 3.3a1 | Added the size modulo 232 to the header |
| 3220 | 94 0C | 3.3a2 | Changed the PEP 380 implementation |
| 3230 | 9E 0C | 3.3 (from 3.3a4) | Reverted changes to the implicit __class__ closure |
| 3250 | B2 0C | 3.4a1 | Positional defaults are evaluated before keyword-only defaults |
| 3260 | BC 0C | 3.4a1 | Added LOAD_CLASSDEREF; locals of a class may override free variables |
| 3270 | C6 0C | 3.4a1 | Various tweaks to the __class__ closure |
| 3280 | D0 0C | 3.4a1 | Removed the implicit class argument |
| 3290 | DA 0C | 3.4a4 | Changes to the __qualname__ computation |
| 3300 | E4 0C | 3.4a4 | More changes to the __qualname__ computation |
| 3310 | EE 0C | 3.4 (from 3.4rc2) | Altered the __qualname__ computation |
| 3320 | F8 0C | 3.5a1 | PEP 465: the matrix multiplication operator |
| 3330 | 02 0D | 3.5b1 | PEP 448: additional unpacking generalisations |
| 3340 | 0C 0D | 3.5b2 | Fixed the evaluation order of dictionary displays |
| 3350 | 16 0D | 3.5 (from 3.5b3) | Added GET_YIELD_FROM_ITER |
| 3351 | 17 0D | 3.5.2 | Fixed BUILD_MAP_UNPACK_WITH_CALL |
Source modification time
At offset 4: the source file’s modification time when it was compiled, as a 32-bit count of seconds since 1 January 1970. Python compares it with the source, and recompiles if the two differ.
Source size
At offset 8: the size of the source file in bytes, modulo 232. Python compares this too, so a file edited within the same second is still caught if its size changed.
File names
Python writes these files to a __pycache__ folder next to the source
and puts the interpreter’s name and version in the file name. The name of an optimised
file changed in 3.5, through PEP 488.
| Source | Compiled by | File |
|---|---|---|
spam.py | CPython 3.3 or 3.4 | __pycache__/spam.cpython-33.pyc, …34.pyc |
spam.py | CPython 3.3 or 3.4 with -O or -OO | __pycache__/spam.cpython-33.pyo, …34.pyo |
spam.py | CPython 3.5 | __pycache__/spam.cpython-35.pyc |
spam.py | CPython 3.5 with -O | __pycache__/spam.cpython-35.opt-1.pyc |
spam.py | CPython 3.5 with -OO | __pycache__/spam.cpython-35.opt-2.pyc |
A spam.pyc placed in a folder by itself, with no source file beside it,
can also be imported.