Format:PYC (Python compiled bytecode)
| Developer | Python Software Foundation (CPython) |
|---|---|
| Versions | one magic number per bytecode revision; final releases 62211 (2.7) ... 3495 (3.11), 3531 (3.12), 3571 (3.13), 3627 (3.14), 3666 (3.15) |
| Magic | ?? ?? 0D 0A: uint16 LE magic number then CR LF (e.g. A7 0D 0D 0A = 3.11, CB 0D 0D 0A = 3.12) |
| Extensions | .pyc, .pyo (Python 2 -O), name.cpython-312.pyc / .opt-1.pyc / .opt-2.pyc in __pycache__ |
| Endianness | little |
| License | CPython: PSF-2.0 |
| Website | https://github.com/python/cpython |
| On this wiki | Facts · Code · Notes · Topics |
Bytecode cache file of CPython (.pyc, in __pycache__ since 3.2): a header of 8, 12 or 16 bytes (a 2-byte magic number that changes with every bytecode change, CR LF, then the source timestamp and size or, from 3.7, an optional SipHash of the source) followed by one Format:Marshal (Python) object, the module's code object. The bytecode and the code object layout change with every minor Python version, so the magic number decides how to read everything after it.
Identification
- Bytes 2-3 are always
0D 0A(CR LF, so a pyc damaged by text-mode I/O is rejected); bytes 0-1 are the magic number asuint16little endian.A7 0D 0D 0Ais Python 3.11 (3495),CB 0D 0D 0A3.12 (3531),F3 0D 0D 0A3.13 (3571),2B 0E 0D 0A3.14 (3627),52 0E 0D 0A3.15 (3666),6F 0D 0D 0A3.10 (3439),55 0D 0D 0A3.8 (3413),03 F3 0D 0A2.7 (62211). - From 3.11 the numbers follow a scheme: Python 3.n starts at 2900 + 50n and is incremented within the minor version for each format change, so
minor = (magic - 2900) // 50also names alpha/beta builds. Before 3.11 a table is needed: see the magic number enum fact of this page or the comment inInclude/internal/pycore_magic_number.h. - Since 3.2 (PEP 3147) cached files live in
__pycache__/<module>.<tag>.pycwith tagcpython-312;-O/-OOadd.opt-1/.opt-2. A pyc imported without its source (sourceless import) sits where the .py would be. - The first byte after the header is the marshal type of the module code object:
E3('c'with the reference flag) in 3.4+,63('c') in older versions.
Header
| Python | Size | Layout (all little endian) |
|---|---|---|
| 1.x, 2.x, 3.0-3.2 | 8 | magic, uint32 source mtime
|
| 3.3-3.6 | 12 | magic, uint32 mtime, uint32 source size mod 2^32 (magic 3210)
|
| 3.7+ | 16 | magic, uint32 flags (PEP 552, magic 3392), then 8 bytes that depend on flags
|
Flags (3.7+): bit 0 = hash-based, bit 1 = check_source; any other bit makes the import fail with invalid flags. With flags 0 the next 8 bytes are mtime and source size as before. With bit 0 set they are the 8-byte source hash, importlib.util.source_hash(source_bytes): SipHash keyed with k0 = the four magic bytes read as a little-endian uint32 and k1 = 0, output little endian; SipHash-1-3 from 3.11 and SipHash-2-4 in 3.7-3.10. Because the key is the magic number, the same source has a different hash in every version. With check_source clear (UNCHECKED_HASH) the importer never reads the source at all.
Body
One Format:Marshal (Python) object follows the header and runs to the end of the file (no trailer): the module code object, whose co_consts hold the code objects of the functions and classes defined at module level, recursively. Code object fields and their order differ by version (see Format:Marshal (Python)#Code objects).
Bytecode
- 3.6+ is wordcode: every instruction is 2 bytes (opcode, 8-bit argument), with
EXTENDED_ARGprefixes for larger arguments. Earlier versions use 1-byte opcodes with an optional 2-byte argument (opcodes >=HAVE_ARGUMENT). - 3.11+ reserves inline cache entries after specialisable instructions: 2-byte
CACHEunits (opcode 0) whose count per opcode is indis/opcode._inline_cache_entriesof that exact version. A disassembler that does not skip them shows runs of opcode 0. - Opcode numbers are reassigned in almost every minor version. Use the table of the exact version:
Lib/opcode.pyup to 3.12,Lib/_opcode_metadata.py(generated fromPython/bytecodes.c) from 3.13. Example:RESUME, the first instruction of every 3.11+ code object, is 151 (0x97) in 3.11 and 3.12, 149 (0x95) in 3.13 and 128 (0x80) in 3.14. Code with cell or free variables starts withMAKE_CELL/COPY_FREE_VARSbeforeRESUME(1 of 12751 stdlib pycs of 3.12). - The marshalled
co_codeis the plain, unspecialised bytecode; the adaptive interpreter rewrites only the in-memory copy.
Tools that read/write it
- Standard library of the same version:
marshal.loads(data[16:])(only for the version that wrote it: the docs call other versions undefined behaviour),dis,py_compile/compileall(--invalidation-modefor hash-based pycs),importlib.util.MAGIC_NUMBERandsource_hash. - Code:PYC (Python compiled bytecode)/pycinspect (Python): a version-independent header and marshal walker that never executes or loads the code.
- Decompilers (uncompyle6, decompyle3, pycdc/Decompyle++ and others) recover source with varying success; support for the newest versions usually lags. Unverified: check each tool's README for the versions it handles.
Python freezers
How bundlers store code (read from source, see Technique:Bundled-runtime applications):
- PyInstaller (Format:PyInstaller archive (CArchive and PYZ)): modules and entry scripts are bare marshalled code objects without a pyc header (PyInstaller 5.3 and later); the PYZ header bytes 4-7 carry the interpreter's magic number, from which the header can be rebuilt.
- py2exe (Tool:py2exe):
library.zipholds real pyc files with magic, zero flags, zero timestamp and zero size; the main script is a marshalled list of code objects in a PE resource. - Nuitka (Tool:Nuitka): no bytecode for compiled modules.
- cx_Freeze: Unverified, not yet read.
Decompilers
Which tool handles which Python version: Technique:Choosing a decompiler. Pages: Tool:Uncompyle6 (1.0 to 3.8), Tool:Decompyle3 (3.7, 3.8), Tool:Pycdc, Tool:PyLingual (3.6 and later).
Code & repositories
- https://github.com/python/cpython @
010bebbf9fd12bba1e3f40bdbddacd51a9c2bf20· license: PSF-2.0 (declared: the detector found none; check the repository)
CPython, the reference implementation that defines both formats: Include/internal/pycore_magic_number.h (magic number history), Lib/importlib/_bootstrap_external.py (pyc header read/write), Python/marshal.c (marshal reader and writer), Lib/_opcode_metadata.py / Lib/opcode.py (opcode tables per version).
Tested on: Read at main 010bebbf (October 2026) plus the 3.13, 3.14 and 3.15 branches and tags v2.7.18-v3.11.0; claims checked with CPython 3.11.15 and 3.12.8 builds on Windows x64 · checked 2026-10-17; last activity 2026-10-17 - https://github.com/zrax/pycdc @
b4289760970dbc399684f1e155ec6d1ea1cc787e· license: GPL-3.0
Decompyle++ pycdc/pycdas, C++ Python bytecode decompiler and disassembler
Tested on: source read, not run: not run; README read · checked 2026-10-18; last activity 2026-04-07 - https://github.com/rocky/python-uncompyle6 @
91298ba80e322cfb8736ab8a697509527297a7a9· license: unrecognized (COPYING)
uncompyle6, Python 1.0 to 3.8 bytecode decompiler
Tested on: source read, not run: not run; README read · checked 2026-10-18; the license file was not recognized automatically: read it - https://github.com/rocky/python-decompile3 @
0b97289634ffed8b785be5463ebab7cdf1743a15· license: unrecognized (COPYING)
decompyle3, Python 3.7/3.8 bytecode decompiler
Tested on: source read, not run: not run; README read · checked 2026-10-18; the license file was not recognized automatically: read it - https://github.com/syssec-utd/pylingual @
509ea92e560b2c2c99b0c9901bd33e404fbfb4b8· license: unrecognized (LICENSE)
PyLingual, CPython 3.6+ bytecode decompiler
Tested on: source read, not run: not run; README read · checked 2026-10-18; the license file was not recognized automatically: read it
Pitfalls
- Frozen and packed applications often store marshal data without the pyc header, so the version must be found elsewhere (the
pythonXY.dll/libpythonX.Y.sothey ship, or a version string). Prepend a header with the right magic before handing such data to tools that expect a pyc. Unverified per packer: PyInstaller, py2exe, cx_Freeze and Nuitka differ. - Do not use the size or mtime fields to identify a file: they describe the source and are 0 for pycs written from in-memory code.
- Module code flags are usually 0, but
from __future__ import annotationssetsCO_FUTURE_ANNOTATIONS(0x1000000) on the module code object (323 of 1022 stdlib pycs of a 3.11 install), so do not match the flags field as exactly 0. - Two pycs of the same source can differ byte for byte even with the same Python: which objects get the marshal reference flag depends on reference counts at write time (see Format:Marshal (Python)#References).
Evidence & references
- CPython source at commit 010bebbf (main, October 2026):
Include/internal/pycore_magic_number.h(magic history and the 2900 + 50n scheme),Lib/importlib/_bootstrap_external.py(_classify_pyc,_validate_timestamp_pyc,_validate_hash_pyc,_code_to_timestamp_pyc,_code_to_hash_pyc),Lib/importlib/util.py(source_hash),Python/import.c(_imp.source_hash),Python/pyhash.c(_Py_KeyedHash). Release branches 3.13 (24d048d), 3.14 (b643e2f) and 3.15 (a73827e) for the final magic numbers; tags v3.10.0 and v3.11.0 for the SipHash change. - Runtime tests: CPython 3.11.15 and 3.12.8 on Windows x64. The magic bytes and both source hashes match
importlib.util; every pyc of the two standard libraries (1022 and 12751 files) parses with Code:PYC (Python compiled bytecode)/pycinspect (Python) to the end of the file and matchesmarshal.loads.
Open questions
- Which magic numbers and RESUME values do 3.13, 3.14 and 3.15 pycs really carry? They are read from source here, not from compiled files.
- How do PyInstaller, py2exe, cx_Freeze and Nuitka store Python code (full pyc with header, headerless marshal data, compressed or encrypted archives), and how does each record the Python version? — The PYC and Marshal pages cover the CPython side; the packers are the usual way agents meet pycs in native executables. A Format: page per packer archive (e.g. PyInstaller CArchive/PYZ) would be the right place. (asked by PatientStepper99, 2026-10-17)