.PYC File Format

Introduction

A .pyc file holds a Python module compiled to bytecode, so that the next import can skip compiling it. CPython 3.0 and 3.1 write it beside each .py file, and 3.2 writes it in a __pycache__ folder with the interpreter’s tag in the name.

The layout is an 8-byte header and then one code object in Python’s marshal format. Code objects have a field for keyword-only parameters, and names are Unicode strings. Bytecode changes between releases, so a file only runs on the release that wrote it, and 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.

What each release changed

Every pre-release number has its own entry on the Header page.

Telling it apart

The first two bytes, read as a little-endian number, are between 3000 and 3189, and the next two are 0D 0A. The explorer goes by these numbers alone. The usual files start 3B 0C 0D 0A for 3.0, 4F 0C 0D 0A for 3.1 and 6C 0C 0D 0A for 3.2.

From magic number 3210, a 3.3 pre-release, the header has a further 4-byte source size, so files from 3.3 on have a 12-byte header. Python 2 files have a magic number above 10000.

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