How to Disassemble Python Bytecode (with the dis Module)

CPython compiles each function, class, and module into a code object — a bundle holding the bytecode plus its constants, names, and metadata. That bytecode is a sequence of opcodes (one-byte instructions) that push and pop values on an evaluation stack. It's what gets cached in the __pycache__/*.pyc files, and it's what the interpreter loop actually executes.

You don't normally see it because it's an implementation detail — but it's fully inspectable, and reading it demystifies a lot of Python. The tool for that is dis.

Pass any function to dis.dis() and it prints the disassembly. Here's a trivial adder, disassembled on Python 3.14 (real output):

import dis

def add(a, b):
    return a + b

dis.dis(add)

#   5   RESUME                            0
#
#   6   LOAD_FAST_BORROW_LOAD_FAST_BORROW 1 (a, b)
#       BINARY_OP                         0 (+)
#       RETURN_VALUE

Read the columns left to right: the source line number (6), the opcode (BINARY_OP), its argument (0), and a human-readable argrepr in parentheses ((+)). RESUME is a no-op marker CPython places at the start of every frame.

Most opcodes are named for exactly what they do. A handful cover the vast majority of real code:

f-strings are a nice example of the compiler doing work up front. This function builds a greeting:

def greet(name):
    return f"Hello, {name}!"

# 10   LOAD_CONST      0 ('Hello, ')
#      LOAD_FAST_BORROW 0 (name)
#      FORMAT_SIMPLE
#      LOAD_CONST      1 ('!')
#      BUILD_STRING    3
#      RETURN_VALUE

There's no runtime string parsing: the literal parts 'Hello, ' and '!' are already constants, the variable is formatted with FORMAT_SIMPLE, and BUILD_STRING 3 concatenates the three pieces. (In older versions this opcode was FORMAT_VALUE — another version difference.)

The real structure shows up with closures. Here make_counter returns an inner function inc that mutates a captured variable — so the compiler has to set up cells (co_cellvars) and free variables (co_freevars):

def make_counter(start=0):
    count = start
    def inc(step=1):
        nonlocal count
        count += step
        return count
    return inc

# make_counter:
#   MAKE_CELL         2 (count)
#   ...
#   STORE_DEREF       2 (count)
#   LOAD_CONST        1 (<code object inc at 0x…, line 22>)
#   MAKE_FUNCTION
#   SET_FUNCTION_ATTRIBUTE 8 (closure)
#
# Disassembly of <code object inc …>:
#   COPY_FREE_VARS    1
#   LOAD_DEREF        1 (count)
#   LOAD_FAST_BORROW  0 (step)
#   BINARY_OP        13 (+=)
#   STORE_DEREF       1 (count)
#   LOAD_DEREF        1 (count)
#   RETURN_VALUE

Notice the nested <code object inc> — it's stored right inside the outer function's co_consts. dis recurses into it automatically. MAKE_CELL, STORE_DEREF, COPY_FREE_VARS, and LOAD_DEREF are the closure machinery: the shared count lives in a cell so both functions see the same variable.

This is the part people trip over: bytecode is not stable across releases. The exact same source compiles to different instructions on different Pythons. A few concrete, verifiable changes:

• 3.11 introduced the adaptive specializing interpreter and inline CACHE slots — you'll see CACHE entries between real ops when you show them.
• 3.12 inlined list/set/dict comprehensions (no separate <listcomp> code object anymore) and added RETURN_CONST.
• 3.14 fused loads into superinstructions like LOAD_FAST_BORROW_LOAD_FAST_BORROW, as we saw above.

I checked the comprehension change directly. On Python 3.14, a list comprehension compiles with no nested code object — it's inlined into the surrounding code:

code = compile(
    "squares = [n*n for n in range(10) if n % 2 == 0]",
    "<demo>", "exec")

print([type(c).__name__ for c in code.co_consts])
# -> ['int', 'NoneType']       # no <code object <listcomp>>
print(any(hasattr(c, 'co_code') for c in code.co_consts))
# -> False

On Python 3.11 that same line produces a separate <listcomp> code object in co_consts. This is exactly why the disassembler tool lets you switch the CPython version (3.11 / 3.12 / 3.13) — you can watch the structure change instead of taking my word for it.

Reading bytecode makes one security fact undeniable: a compiled Python file gives your code away. Every string and number literal is stored, in plain text, in the code object's co_consts. Here's a file with an "embedded secret", compiled and inspected — no decompiler needed:

src = 'API_KEY = "sk-live-9f83kd02n"\nif user == "admin":\n    grant()\n'
code = compile(src, "app.py", "exec")

code.co_consts
# -> ('sk-live-9f83kd02n', 'admin', None)
code.co_names
# -> ('API_KEY', 'user', 'grant')

The API key, the string it's compared against, and every name are all sitting in the open — and that's *before* anyone runs a decompiler like pycdc to rebuild the source. Shipping .pyc files (or freezing to an .exe, which just bundles .pyc) hides none of this.