.PYC File Format

Introduction

A .pyc file holds a Python module compiled to bytecode, so that the next import can skip compiling it. CPython 2.1 and 2.2 write one beside each .py file they import: foo.py gives foo.pyc, or foo.pyo with the -O option.

The layout is an 8-byte header and then one code object in Python’s marshal format. The numbers in the code object are 16-bit, and it has two fields for nested scopes, co_freevars and co_cellvars, which is what sets these releases apart from earlier ones. Bytecode changes between releases, so a file only runs on the release that wrote it. The magic number says which 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. See all the .pyc variations.

Structure

All numbers are little-endian. The header is 8 bytes and the rest of the file is one object, the module’s code object. Nothing follows it.

The code object holds the module’s instructions, its constants and names, and a table of line numbers.

What each release changed

Telling it apart

The first two bytes, read as a little-endian number, are 60202, 60203, 60717 or 60718, and the next two are 0D 0A. The explorer goes by these numbers alone.

Python 1.5 to 2.0 files also have 16-bit numbers in their code objects but do not have the two free and cell variable fields. Python 2.3 files have those fields but store every number in 32 bits.

Variants

• Python 1.5 to 2.0 bytecode – 8-byte header and 16-bit numbers in the code object
• Python 2.1 and 2.2 bytecode – adds co_freevars and co_cellvars
• Python 2.3 to 2.7 bytecode – the numbers in a code object become 32-bit
• Python 3.0 to 3.2 bytecode – adds co_kwonlyargcount; names are Unicode
• Python 3.3 to 3.5 bytecode – 12-byte header, with the source size
• Python 3.6 bytecode – two-byte instructions
• Python 3.7 bytecode – 16-byte header, with flags and hash-based files
• Python 3.8 and 3.9 bytecode – adds co_posonlyargcount
• Python 3.10 bytecode – a line table 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