.PYC File Format

Introduction

A .pyc file of this format holds one Python module compiled by CPython 3.7, so that the next import can skip compiling it. Python writes it to a __pycache__ folder beside the source, named module.cpython-37.pyc, and only CPython 3.7 will load it.

The file is a 16-byte header followed by the module’s code object, written in Python’s marshal format. The code object holds the instructions as two-byte pairs, its constants and names, and a table that maps instructions to source lines. Functions and classes defined in the module are further code objects inside its constants.

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

All numbers are little-endian. There are two ways to fill the 8 bytes after the flags: most files record the source’s date and size, and a hash-based file records a hash of the source instead.

Every code object holds its instructions in co_code and its line numbers in co_lnotab.

What this release changed

Python 3.7 is the first release whose files can be checked by a hash of the source, and the header grew by four bytes to make room for the flags that say so. The numbers below come from the magic number list in CPython’s source.

Telling it apart

The first two bytes, read as a little-endian number, are the magic number, and they must be followed by 0D 0A. The explorer treats 3390 to 3399 as this format: a final 3.7 file starts 42 0D 0D 0A. The magic number settles it alone. Below 3390 a file has no flags field, and from 3400 a code object may carry a count of positional-only parameters.

Files with magic 3390 or 3391, from the 3.7 alphas, have no flags field and a 12-byte header. The explorer reads them correctly.

Variants

• Python 1.5 to 2.0 bytecode – 16-bit numbers in a code object, an 8-byte header
• Python 2.1 and 2.2 bytecode – adds cell and free variables
• Python 2.3 to 2.7 bytecode – the numbers become 32-bit
• Python 3.0 to 3.2 bytecode – adds co_kwonlyargcount; names are Unicode
• Python 3.3 to 3.5 bytecode – a 12-byte header with the source size
• Python 3.6 bytecode – two-byte instructions
• Python 3.7 bytecode – a 16-byte header with flags and hash-based files
• Python 3.8 and 3.9 bytecode – adds co_posonlyargcount
• Python 3.10 bytecode – co_linetable replaces co_lnotab; jumps count instructions
• Python 3.11 and later bytecode – locals in one list, a location table, an exception table and inline caches

Links