.PYC File Format

Python 3.10 bytecode

Introduction

When CPython imports a module from a .py file, it compiles the source to bytecode and saves the result as a .pyc file in a __pycache__ folder beside the source. The next import loads the .pyc file and skips the compiler. The file holds the module’s code object: its instructions, constants and names, with the code object of every function and class nested inside.

This page covers the format written by Python 3.10. Line numbers are stored in co_linetable, a table of byte ranges and line steps, as PEP 626 specifies, and a jump’s argument counts instructions rather than bytes.

A file only runs on the release that wrote it. The magic number at the start says which one that is.

A .pyc file dropped on any page of this site opens in the explorer, which shows its structure, a disassembly and each code object.

Structure

A file is a 16-byte header followed by one object in Python’s marshal format, the module’s code object. All numbers are little-endian.

  1. 0magic: 3439, then 0D 0A4 bytes
  2. 4flags: 0 for a date check, 1 or 3 for a hash check4 bytes
  3. 8source_mtime and source_size, or source_hash8 bytes
  4. 16code object of the module, one marshal objectvaries
The parts of a .pyc file; nothing follows the code object

The code object holds counts, flags, the instructions as a byte string, a tuple of constants (which holds nested code objects), the names it uses, and a line table. Exception handling is done by instructions in the code, not by a table.

What Python 3.10 changed

  • Line numbers moved from co_lnotab to co_linetable, which can say that an instruction has no line at all (PEP 626, magic 3431).
  • A jump’s argument counts instructions instead of bytes (magic 3435).
  • match statements added MATCH_CLASS, MATCH_KEYS, MATCH_MAPPING, MATCH_SEQUENCE, GET_LEN and COPY_DICT_WITHOUT_KEYS (PEP 634, magic 3434).
  • GEN_START and ROT_N were added.
  • The annotations passed to MAKE_FUNCTION became a tuple, not a dictionary.
  • RERAISE restores f_lasti when its argument is nonzero.

Each pre-release number is on the header page. Files of 3430 to 3434 are pre-releases only and differ in the points above.

Telling it apart

The first two bytes, little-endian, are the magic number, and the next two are 0D 0A. The final number of Python 3.10 is 3439, and its pre-releases used 3430 to 3438. The explorer takes this range and reads the file strictly: only 0, 1 and 3 are valid flags, and the code object must fill the rest of the file exactly.

Python 3.11 files have a magic number of 3450 or more, and a code object with no co_nlocals and with an exception table.

00000000  6F 0D 0D 0A 00 00 00 00 00 F1 53 65 06 00 00 00
The start of a Python 3.10 file: magic 3439, flags 0, modification time 1700000000, source size 6

Variants

Links

Software

  • CPython – the Python interpreter, which writes and loads these files; python -m dis shows the bytecode (Windows, macOS, Linux)
  • Decompyle++ (pycdc) – disassembler and decompiler for .pyc files of many Python versions (Windows, macOS, Linux)

Developers

  • dis – Python’s own bytecode disassembler (Python)
  • marshal – Python’s own module for the object format of the body (Python)
  • py_compile – Python’s own module that writes .pyc files (Python)
  • importlib – Python’s import system, which reads and checks them (Python)
  • xdis – cross-version disassembler (Python)

Reference

  • dis – Python’s documentation of its bytecode instructions (Python 3.10)
  • marshal – Python’s documentation of the module and its version numbers
  • importlib – Python’s documentation of the import system
  • PEP 3147 – the __pycache__ folder and its file names
  • PEP 552 – the flags field and hash-based .pyc files
  • PEP 626 – precise line numbers for tracing
  • lnotab_notes.txt – CPython’s description of the line number table (Python 3.10)