.PYC File Format

Introduction

A .pyc file of this format holds one Python module compiled by CPython 3.3, 3.4 or 3.5, so that the next import can skip compiling it. Python writes it to a __pycache__ folder beside the source, with a name such as module.cpython-34.pyc, and only the release that wrote it will load it. With the -O or -OO options, CPython 3.3 and 3.4 write the same format to a file ending in .pyo.

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, of one or three bytes each, 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 each release changed

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 3190 to 3359 as this format: 9E 0C 0D 0A is a final 3.3 file, EE 0C 0D 0A 3.4 and 16 0D 0D 0A or 17 0D 0D 0A 3.5. The magic number settles it alone. A number below 3190 belongs to an earlier release, and 3360 or more belongs to Python 3.6.

Files with magic 3190 or 3200, from the first 3.3 alpha, have no source_size and an 8-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