Python 3.0 to 3.2 bytecode: instructions

A code object’s co_code holds its instructions one after another. Python’s virtual machine is a stack machine: most instructions take values from a stack and leave a result there. Below, TOS is the top of the stack, TOS1 the item under it, TOS2 the one under that.

Encoding

An instruction is one byte, the opcode, or three bytes when the opcode takes an argument. Opcodes of 90 or more do; this dividing line is called HAVE_ARGUMENT. The argument is an unsigned 16-bit little-endian number directly after the opcode. So 7C 03 00 is LOAD_FAST 3 and 53 is RETURN_VALUE.

EXTENDED_ARG goes before an instruction whose argument does not fit in two bytes. Its own argument becomes the high 16 bits of the next instruction’s argument. Its number changes between releases.

Arguments and jumps

What the argument means depends on the opcode.

LOAD_CONST: an index into co_consts.
STORE_NAME, DELETE_NAME, STORE_ATTR, DELETE_ATTR, STORE_GLOBAL, DELETE_GLOBAL, LOAD_NAME, LOAD_ATTR, IMPORT_NAME, IMPORT_FROM, LOAD_GLOBAL: an index into co_names.
LOAD_FAST, STORE_FAST, DELETE_FAST: an index into co_varnames.
LOAD_CLOSURE, LOAD_DEREF, STORE_DEREF, DELETE_DEREF: a slot in the cell and free variable storage. The name is co_cellvars[i], or co_freevars[i - len(co_cellvars)] once i is past the cell variables.
COMPARE_OP: an index into the table of comparison operators.
MAKE_FUNCTION and MAKE_CLOSURE: the low 8 bits count positional defaults, the next 8 bits count keyword-only defaults, and the bits from 16 up give the number of annotations.
UNPACK_EX: the low byte is the number of values before the list, the high byte the number after.

A jump’s argument is counted in bytes of co_code.

Relative, counted from the instruction after the jump, so the target is the jump’s own offset, plus 3, plus the argument: JUMP_FORWARD, FOR_ITER, SETUP_LOOP, SETUP_EXCEPT, SETUP_FINALLY, and, in 3.2, SETUP_WITH. In 3.0, JUMP_IF_FALSE and JUMP_IF_TRUE are relative too.
Absolute, where the argument is the offset to go to: JUMP_ABSOLUTE, CONTINUE_LOOP, and, from 3.1, JUMP_IF_FALSE_OR_POP, JUMP_IF_TRUE_OR_POP, POP_JUMP_IF_FALSE and POP_JUMP_IF_TRUE.

Comparison operators

The argument of COMPARE_OP.

Argument	Operator
0	`<`
1	`<=`
2	`==`
3	`!=`
4	`>`
5	`>=`
6	`in`
7	`not in`
8	`is`
9	`is not`
10	exception match, for `except` clauses
11	`BAD`, the end of the list

Every opcode

Numbers are from Lib/opcode.py at the 3.0.1, 3.1.5 and 3.2.6 tags. A dash means the release does not have the opcode. Meanings follow Python’s dis documentation for 3.0 and 3.2.

Name	3.0	3.1	3.2	Meaning
`STOP_CODE`	0	0	0	Marks the end of code for the compiler. The interpreter does not use it
`POP_TOP`	1	1	1	Removes TOS
`ROT_TWO`	2	2	2	Swaps the two top items
`ROT_THREE`	3	3	3	Lifts the second and third items one place and moves the top down to third
`DUP_TOP`	4	4	4	Duplicates the reference at TOS
`ROT_FOUR`	5	5	–	Lifts the second, third and fourth items one place and moves the top down to fourth
`DUP_TOP_TWO`	–	–	5	Duplicates the two references on top of the stack, keeping their order
`NOP`	9	9	9	Does nothing. A placeholder for the bytecode optimiser
`UNARY_POSITIVE`	10	10	10	`TOS = +TOS`
`UNARY_NEGATIVE`	11	11	11	`TOS = -TOS`
`UNARY_NOT`	12	12	12	`TOS = not TOS`
`UNARY_INVERT`	15	15	15	`TOS = ~TOS`
`SET_ADD`	17	146	146	Adds an item to a set, for set comprehensions. In 3.0 it has no argument: `set.add(TOS1, TOS)`. From 3.1 it pops TOS and adds it to the set `TOS1[-i]`, where `i` is the argument
`LIST_APPEND`	18	145	145	Appends an item to a list, for list comprehensions. In 3.0 it has no argument: `list.append(TOS1, TOS)`. From 3.1 it pops TOS and appends it to the list `TOS[-i]`, where `i` is the argument
`BINARY_POWER`	19	19	19	`TOS = TOS1 ** TOS`
`BINARY_MULTIPLY`	20	20	20	`TOS = TOS1 * TOS`
`BINARY_MODULO`	22	22	22	`TOS = TOS1 % TOS`
`BINARY_ADD`	23	23	23	`TOS = TOS1 + TOS`
`BINARY_SUBTRACT`	24	24	24	`TOS = TOS1 - TOS`
`BINARY_SUBSCR`	25	25	25	`TOS = TOS1[TOS]`
`BINARY_FLOOR_DIVIDE`	26	26	26	`TOS = TOS1 // TOS`
`BINARY_TRUE_DIVIDE`	27	27	27	`TOS = TOS1 / TOS`
`INPLACE_FLOOR_DIVIDE`	28	28	28	In-place `TOS = TOS1 // TOS`
`INPLACE_TRUE_DIVIDE`	29	29	29	In-place `TOS = TOS1 / TOS`
`STORE_MAP`	54	54	54	Stores a key and value pair in a dictionary. Pops the key and value and leaves the dictionary on the stack
`INPLACE_ADD`	55	55	55	In-place `TOS = TOS1 + TOS`
`INPLACE_SUBTRACT`	56	56	56	In-place `TOS = TOS1 - TOS`
`INPLACE_MULTIPLY`	57	57	57	In-place `TOS = TOS1 * TOS`
`INPLACE_MODULO`	59	59	59	In-place `TOS = TOS1 % TOS`
`STORE_SUBSCR`	60	60	60	`TOS1[TOS] = TOS2`
`DELETE_SUBSCR`	61	61	61	`del TOS1[TOS]`
`BINARY_LSHIFT`	62	62	62	`TOS = TOS1 << TOS`
`BINARY_RSHIFT`	63	63	63	`TOS = TOS1 >> TOS`
`BINARY_AND`	64	64	64	`TOS = TOS1 & TOS`
`BINARY_XOR`	65	65	65	`TOS = TOS1 ^ TOS`
`BINARY_OR`	66	66	66	`TOS = TOS1 \| TOS`
`INPLACE_POWER`	67	67	67	In-place `TOS = TOS1 ** TOS`
`GET_ITER`	68	68	68	`TOS = iter(TOS)`
`STORE_LOCALS`	69	69	69	Pops TOS and stores it as the current frame’s `f_locals`. Used in class construction
`PRINT_EXPR`	70	70	70	The expression statement in interactive mode: removes TOS and prints it
`LOAD_BUILD_CLASS`	71	71	71	Pushes `builtins.__build_class__`, which `CALL_FUNCTION` later calls to make a class
`INPLACE_LSHIFT`	75	75	75	In-place `TOS = TOS1 << TOS`
`INPLACE_RSHIFT`	76	76	76	In-place `TOS = TOS1 >> TOS`
`INPLACE_AND`	77	77	77	In-place `TOS = TOS1 & TOS`
`INPLACE_XOR`	78	78	78	In-place `TOS = TOS1 ^ TOS`
`INPLACE_OR`	79	79	79	In-place `TOS = TOS1 \| TOS`
`BREAK_LOOP`	80	80	80	Ends a loop, for a `break` statement
`WITH_CLEANUP`	81	81	81	Cleans up the stack when a `with` block exits and calls the context manager’s `__exit__`
`RETURN_VALUE`	83	83	83	Returns TOS to the caller
`IMPORT_STAR`	84	84	84	Copies every name not starting with `_` from the module at TOS into the local namespace, then pops the module
`YIELD_VALUE`	86	86	86	Pops TOS and yields it from a generator
`POP_BLOCK`	87	87	87	Removes one block from the block stack
`END_FINALLY`	88	88	88	Ends a `finally` clause. The interpreter re-raises the exception, returns or goes on, as it had recorded
`POP_EXCEPT`	89	89	89	Removes an exception handler block from the block stack and restores the exception state from the three values popped
`STORE_NAME`	90	90	90	`name = TOS`. The argument is an index into `co_names`
`DELETE_NAME`	91	91	91	`del name`. The argument is an index into `co_names`
`UNPACK_SEQUENCE`	92	92	92	Unpacks TOS into the given number of values, pushed right to left
`FOR_ITER`	93	93	93	TOS is an iterator. Calls its `__next__()`. A new value is pushed, with the iterator left below it. When exhausted, TOS is popped and the byte counter moves on by the argument
`UNPACK_EX`	94	94	94	Unpacks an iterable for a starred target. One value becomes a list of the leftovers. The values are pushed right to left
`STORE_ATTR`	95	95	95	`TOS.name = TOS1`. The argument is an index into `co_names`
`DELETE_ATTR`	96	96	96	`del TOS.name`. The argument is an index into `co_names`
`STORE_GLOBAL`	97	97	97	As `STORE_NAME`, but stores a global
`DELETE_GLOBAL`	98	98	98	As `DELETE_NAME`, but deletes a global
`DUP_TOPX`	99	99	–	Duplicates the top items, keeping their order. The argument is how many, from 1 to 5
`LOAD_CONST`	100	100	100	Pushes `co_consts[argument]`
`LOAD_NAME`	101	101	101	Pushes the value of `co_names[argument]`
`BUILD_TUPLE`	102	102	102	Pops the given number of items and pushes them as a tuple
`BUILD_LIST`	103	103	103	As `BUILD_TUPLE`, but makes a list
`BUILD_SET`	104	104	104	As `BUILD_TUPLE`, but makes a set
`BUILD_MAP`	105	105	105	Pushes a new dictionary, pre-sized to hold the given number of entries
`LOAD_ATTR`	106	106	106	Replaces TOS with `getattr(TOS, co_names[argument])`
`COMPARE_OP`	107	107	107	Compares TOS1 with TOS. The argument indexes the operators
`IMPORT_NAME`	108	108	108	Imports the module `co_names[argument]`. TOS and TOS1 are popped and give the `fromlist` and `level` arguments. The module is pushed
`IMPORT_FROM`	109	109	109	Loads the attribute `co_names[argument]` from the module at TOS and pushes it
`JUMP_FORWARD`	110	110	110	Moves the byte counter on by the argument
`JUMP_IF_FALSE`	111	–	–	If TOS is false, moves the byte counter on by the argument. TOS is left on the stack
`JUMP_IF_FALSE_OR_POP`	–	111	111	If TOS is false, sets the byte counter to the argument and leaves TOS on the stack. Otherwise TOS is popped
`JUMP_IF_TRUE`	112	–	–	If TOS is true, moves the byte counter on by the argument. TOS is left on the stack
`JUMP_IF_TRUE_OR_POP`	–	112	112	If TOS is true, sets the byte counter to the argument and leaves TOS on the stack. Otherwise TOS is popped
`JUMP_ABSOLUTE`	113	113	113	Sets the byte counter to the argument
`POP_JUMP_IF_FALSE`	–	114	114	If TOS is false, sets the byte counter to the argument. TOS is popped
`POP_JUMP_IF_TRUE`	–	115	115	If TOS is true, sets the byte counter to the argument. TOS is popped
`LOAD_GLOBAL`	116	116	116	Pushes the global `co_names[argument]`
`CONTINUE_LOOP`	119	119	119	Continues a loop, for a `continue` statement. The argument is the address to jump to
`SETUP_LOOP`	120	120	120	Pushes a loop block. The block is the argument’s size in bytes from the current instruction
`SETUP_EXCEPT`	121	121	121	Pushes a `try` block. The argument points to the first `except` block
`SETUP_FINALLY`	122	122	122	Pushes a `try` block. The argument points to the `finally` block
`LOAD_FAST`	124	124	124	Pushes the local variable `co_varnames[argument]`
`STORE_FAST`	125	125	125	Stores TOS into the local variable `co_varnames[argument]`
`DELETE_FAST`	126	126	126	Deletes the local variable `co_varnames[argument]`
`RAISE_VARARGS`	130	130	130	Raises an exception. The argument is how many parameters the `raise` statement gave, from 0 to 3
`CALL_FUNCTION`	131	131	131	Calls a function. The low byte of the argument is the number of positional arguments, the high byte the number of keyword arguments. On the stack: keyword pairs, the value above each key, then the positional arguments with the rightmost on top, then the function. All are popped and the result is pushed
`MAKE_FUNCTION`	132	132	132	Pushes a new function. TOS is its code. The argument counts its defaults and annotations: see above
`BUILD_SLICE`	133	133	133	Pushes a slice. With argument 2 it is `slice(TOS1, TOS)`; with 3, `slice(TOS2, TOS1, TOS)`
`MAKE_CLOSURE`	134	134	134	As `MAKE_FUNCTION`, and sets the function’s `__closure__`. TOS is the code, TOS1 the tuple of cells
`LOAD_CLOSURE`	135	135	135	Pushes the cell in the given slot of the cell and free variable storage
`LOAD_DEREF`	136	136	136	Pushes the object held by the cell in the given slot
`STORE_DEREF`	137	137	137	Stores TOS into the cell in the given slot
`DELETE_DEREF`	–	–	138	Empties the cell in the given slot. Used by `del`
`CALL_FUNCTION_VAR`	140	140	140	As `CALL_FUNCTION`; TOS is the variable argument list
`CALL_FUNCTION_KW`	141	141	141	As `CALL_FUNCTION`; TOS is the keyword arguments dictionary
`CALL_FUNCTION_VAR_KW`	142	142	142	As `CALL_FUNCTION`; TOS is the keyword arguments dictionary, below it the variable argument tuple
`SETUP_WITH`	–	–	143	Starts a `with` block: loads `__exit__()` for later, calls `__enter__()`, pushes a `finally` block pointing to the argument and pushes the result
`EXTENDED_ARG`	143	143	144	Gives the next instruction the high 16 bits of its argument
`MAP_ADD`	–	147	147	Adds a key and value to a dictionary, for dictionary comprehensions. Pops TOS (the key) and TOS1 (the value), and the dictionary is found from the argument

.PYC File Format – Instructions

Encoding

Arguments and jumps

Comparison operators

Every opcode