.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. Python 3.13 uses four bits, which combine; the lower bits are always clear.

Parameters come first, in the order co_argcount, co_kwonlyargcount and the flags imply: positional ones, then keyword-only ones, then *args, then **kwargs. Other locals follow, then cells that are not parameters, then free variables.

For example, this function compiled under Python 3.13 has four names, a b inner c, whose kinds are the bytes 60 20 20 40:

def outer(a, b):
    c = 1
    def inner():
        return a + c
    return inner

The nested function inner has two names, a and c, whose kind bytes are 80 80, both free variables.

A module of one line, z = [y for y in range(3)], has one name in co_localsplusnames, y, with the kind byte 30: hidden and a fast local. Inside a function the same comprehension’s y is an ordinary local, 20.

Worked example

Here is marshal.dumps(f) of a code object f, compiled under Python 3.13 from this function in t.py, starting at line 1.

def f(a):
    try:
        return a + 1
    except KeyError:
        return 0

The same code’s location table and exception table are decoded on their own pages.