Lesson 27 · Under the hood

Bytecode and the CPython VM

CPython runs your code in two stages. First the compiler turns the source into bytecode: small, simple instructions stored in a code object. Then a virtual machine runs those instructions one at a time, pushing and popping values on a stack. Follow a three-line program, bump.py, through both stages, read its bytecode with the dis module, and see how the VM speeds up code that runs often.

14 min11 steps5 questionsAdvanced

Fig 27 · Interactive

Loading figure…

or ← →

Check yourself

5 quick questions

Pick an answer to see why. Your score saves with your progress.

01A file has a syntax error on its last line. What happens when you run it with python?

CPython compiles the whole file to bytecode before running its first line, so a syntax error stops the program before anything runs.

02The stack holds [8, 1] (1 on top). What does BINARY_OP + leave on the stack?

BINARY_OP pops the top two values (rhs = 1, then lhs = 8), computes lhs + rhs and pushes the result: [9].

03Which module prints the bytecode of a function?

dis, the disassembler: dis.dis(bump) lists each instruction with its argument. The ast module shows the syntax tree instead.

04What does LOAD_FAST n do?

LOAD_FAST pushes a reference to a local variable's value onto the stack. STORE_FAST does the opposite, and global names use LOAD_GLOBAL.

05After bump(4) has run many times, dis.dis(bump, adaptive=True) shows BINARY_OP_ADD_INT. What changed?

Since Python 3.11 the specializing adaptive interpreter (PEP 659) replaces instructions in hot code with versions made for the types it keeps seeing. The source and the results do not change.

Key terms

Glossary

CPython: The standard Python implementation, from python.org, written in C. It compiles code to bytecode and runs it in a virtual machine.
Bytecode: The small, simple instructions CPython compiles your source into. It is an implementation detail and changes between Python versions.
Code object: What the compiler produces for a module or function body: the bytecode plus the local names, constants and the stack size it needs.
Virtual machine (VM): The part of CPython that runs bytecode, one instruction at a time. A machine made of software, not hardware.
Frame: The workspace for one running call: its local variable slots, its value stack and which instruction runs next.
Value stack: A pile of values inside a frame. Instructions push values on top and pop them off; the newest value is always on top.
dis: The standard-library disassembler: dis.dis(f) prints the bytecode of f.
Specializing adaptive interpreter: Since Python 3.11, the VM's habit of swapping instructions in hot code for faster versions made for the types it sees (PEP 659).

Fine print

Notes and sources

The bytecode shown is CPython 3.13's. Bytecode is an implementation detail and changes between versions: CPython 3.14 prints LOAD_FAST_BORROW for the first load and LOAD_SMALL_INT for the two constants. The card shows each instruction's name and what its argument means; dis also prints the raw argument number.
Each instruction is two bytes, an opcode and an argument (since Python 3.6). Some, such as BINARY_OP, are followed by extra cache entries that the adaptive interpreter uses, so co_code is longer than two bytes per line.
When you import a module, CPython saves its compiled bytecode in a __pycache__ folder as a .pyc file, so the next import can skip the compiler. The file you run directly is compiled every time and not cached.
LOAD_FAST pushes a reference to the object, not a copy of it: the stack and the local slot point at the same int.
CPython is the standard implementation, the one from python.org. Others, such as PyPy, run Python code in different ways.

Quiz Unlocks after the last step.