.PYC File Format

Introduction

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

The file is a 12-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.

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

What this release changed

Python 3.6 changed how instructions and line numbers are stored. The numbers below come from the magic number list in CPython’s source; the full list is on the Header page.

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 3360 to 3389 as this format: a final 3.6 file starts 33 0D 0D 0A. The magic number settles it alone. Below 3360 instructions take one or three bytes, and from 3392 the header is 16 bytes.

Files with magic 3360 or 3361, from before two-byte instructions went in at 3370, have one-byte and three-byte instructions. 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