.PYC File Format

Introduction

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

This page covers the layout those three releases share: an 8-byte header, then one code object in Python’s marshal format, with every number in the code object stored in 16 bits. Bytecode changes between releases, so a file only runs on the release that wrote it. The magic number at the start 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. Functions and classes defined in the module are code objects inside its constants.

What each release changed

Telling it apart

Only the first two bytes matter. Read as a little-endian number they are 20121, 50428, 50823 or 50824, and the next two bytes are 0D 0A. The explorer goes by these numbers alone: the code object has no version field of its own.

The nearest other layout is Python 2.1 and 2.2. Its numbers are also 16-bit, but its magic numbers are different and its code objects have two more fields, co_freevars and co_cellvars.

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