.PYC File Format – Code object

Fields

The fields are written in this order with no separators. An “i32” field is a little-endian 32-bit number with no type byte of its own; every other field is a marshal object.

There are no co_nlocals, co_varnames, co_cellvars or co_freevars fields in the file. Python rebuilds them from the two localsplus fields when it loads the file.

co_flags

Each bit is named by Python’s inspect module with the prefix CO_, or for a future feature in the __future__ module.

Only barry_as_FLUFL and annotations set their bit when the source imports them. The other __future__ features are already on in Python 3, so the compiler accepts their import and sets nothing; their bits appear only in code compiled by compile() with that flag passed explicitly, never in a .pyc file written by the importer.

co_localspluskinds

Each byte describes the name at the same position in co_localsplusnames. Bits combine.

For example, this function has seven names. Worked out from the rules, their kinds are the bytes 22 26 24 2A 2C 20 40:

def outer(a, /, b, *c, d=1, **e):
    x = a
    def inner():
        return x
    return inner

Keyword-only arguments come after the positional ones and before *args and **kwargs. The nested function inner has one name, x, whose kind byte is 80, a free variable.

Worked example

This code object was built by hand to show the layout, for the function below in t.py, starting at line 1. Its instructions are RESUME with its cache unit, LOAD_FAST_BORROW 0 and RETURN_VALUE. It is a valid Python 3.15 code object, but there is no 3.15 interpreter here to compare it with, and the compiler’s own output may differ in details such as co_consts.

def f(a):
    return a

The line numbers page explains the location table’s entries, and the exception table page a table with handlers.