Python 3.3 to 3.5 bytecode: instructions

A code object’s co_code is a string of instructions, which CPython runs on a stack, with a separate block stack for loops and try statements.

Encoding

An opcode is one byte. An opcode of 90 (HAVE_ARGUMENT) or more is followed by a 16-bit little-endian argument, making three bytes. Below 90 there is no argument and the instruction is one byte.

EXTENDED_ARG. An argument that does not fit in 16 bits has an EXTENDED_ARG instruction before it. Its argument supplies the top 16 bits, so an argument of 0x00012345 is 90 01 00 and then the instruction with argument 45 23.

Jumps. A jump’s argument is a count of bytes. A relative jump (JUMP_FORWARD, FOR_ITER, the SETUP_* instructions) counts from the instruction after it, three bytes further on. An absolute jump (JUMP_ABSOLUTE, CONTINUE_LOOP, POP_JUMP_IF_*, JUMP_IF_*_OR_POP) is an offset from the start of co_code.

In the table, TOS is the top of the stack and TOS1 the value below it; “–” means the instruction is not in that release. Number 69 is STORE_LOCALS in 3.3 and GET_YIELD_FROM_ITER in 3.5, and number 81 is WITH_CLEANUP in 3.3 and 3.4 and WITH_CLEANUP_START in 3.5, so the release decides the name.

Opcodes

Name	3.3	3.4	3.5	Meaning
`POP_TOP`	1	1	1	Removes TOS
`ROT_TWO`	2	2	2	Swaps the top two values
`ROT_THREE`	3	3	3	Moves the second and third values up; TOS goes to third place
`DUP_TOP`	4	4	4	Pushes a copy of TOS
`DUP_TOP_TWO`	5	5	5	Pushes copies of the top two values, in the same order
`NOP`	9	9	9	Does nothing
`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`
`BINARY_MATRIX_MULTIPLY`	–	–	16	Pops two values, pushes `TOS1 @ TOS`
`INPLACE_MATRIX_MULTIPLY`	–	–	17	Pops two values, pushes `TOS1 @ TOS` done in place
`BINARY_POWER`	19	19	19	Pops two values, pushes `TOS1 ** TOS`
`BINARY_MULTIPLY`	20	20	20	Pops two values, pushes `TOS1 * TOS`
`BINARY_MODULO`	22	22	22	Pops two values, pushes `TOS1 % TOS`
`BINARY_ADD`	23	23	23	Pops two values, pushes `TOS1 + TOS`
`BINARY_SUBTRACT`	24	24	24	Pops two values, pushes `TOS1 - TOS`
`BINARY_SUBSCR`	25	25	25	Pops two values, pushes `TOS1[TOS]`
`BINARY_FLOOR_DIVIDE`	26	26	26	Pops two values, pushes `TOS1 // TOS`
`BINARY_TRUE_DIVIDE`	27	27	27	Pops two values, pushes `TOS1 / TOS`
`INPLACE_FLOOR_DIVIDE`	28	28	28	Pops two values, pushes `TOS1 // TOS` done in place
`INPLACE_TRUE_DIVIDE`	29	29	29	Pops two values, pushes `TOS1 / TOS` done in place
`GET_AITER`	–	–	50	`TOS = get_awaitable(TOS.__aiter__())`
`GET_ANEXT`	–	–	51	Pushes `get_awaitable(TOS.__anext__())`
`BEFORE_ASYNC_WITH`	–	–	52	Takes `__aenter__` and `__aexit__` from TOS; pushes `__aexit__` and the result of `__aenter__()`
`STORE_MAP`	54	54	–	Stores a key and value pair in a dictionary; pops the key and value and leaves the dictionary
`INPLACE_ADD`	55	55	55	Pops two values, pushes `TOS1 + TOS` done in place
`INPLACE_SUBTRACT`	56	56	56	Pops two values, pushes `TOS1 - TOS` done in place
`INPLACE_MULTIPLY`	57	57	57	Pops two values, pushes `TOS1 * TOS` done in place
`INPLACE_MODULO`	59	59	59	Pops two values, pushes `TOS1 % TOS` done in place
`STORE_SUBSCR`	60	60	60	`TOS1[TOS] = TOS2`
`DELETE_SUBSCR`	61	61	61	`del TOS1[TOS]`
`BINARY_LSHIFT`	62	62	62	Pops two values, pushes `TOS1 << TOS`
`BINARY_RSHIFT`	63	63	63	Pops two values, pushes `TOS1 >> TOS`
`BINARY_AND`	64	64	64	Pops two values, pushes `TOS1 & TOS`
`BINARY_XOR`	65	65	65	Pops two values, pushes `TOS1 ^ TOS`
`BINARY_OR`	66	66	66	Pops two values, pushes `TOS1 \| TOS`
`INPLACE_POWER`	67	67	67	Pops two values, pushes `TOS1 ** TOS` done in place
`GET_ITER`	68	68	68	`TOS = iter(TOS)`
`STORE_LOCALS`	69	–	–	Pops TOS and uses it as the frame’s locals; used in class construction
`GET_YIELD_FROM_ITER`	–	–	69	Leaves TOS if it is a generator or coroutine; otherwise `TOS = iter(TOS)`
`PRINT_EXPR`	70	70	70	Pops TOS and prints it, as the interactive prompt does
`LOAD_BUILD_CLASS`	71	71	71	Pushes `builtins.__build_class__`
`YIELD_FROM`	72	72	72	Pops TOS and delegates to it as a sub-iterator from a generator
`GET_AWAITABLE`	–	–	73	`TOS = get_awaitable(TOS)`
`INPLACE_LSHIFT`	75	75	75	Pops two values, pushes `TOS1 << TOS` done in place
`INPLACE_RSHIFT`	76	76	76	Pops two values, pushes `TOS1 >> TOS` done in place
`INPLACE_AND`	77	77	77	Pops two values, pushes `TOS1 & TOS` done in place
`INPLACE_XOR`	78	78	78	Pops two values, pushes `TOS1 ^ TOS` done in place
`INPLACE_OR`	79	79	79	Pops two values, pushes `TOS1 \| TOS` done in place
`BREAK_LOOP`	80	80	80	Ends a loop because of a `break` statement
`WITH_CLEANUP`	81	81	–	Cleans up the stack when a `with` block exits, calling `__exit__()`; a true result silences the exception
`WITH_CLEANUP_START`	–	–	81	Starts cleaning up when a `with` block exits: calls `__exit__()` and pushes a value and its result
`WITH_CLEANUP_FINISH`	–	–	82	Pops the two values `WITH_CLEANUP_START` pushed; a true result from `__exit__()` silences the exception
`RETURN_VALUE`	83	83	83	Returns TOS to the caller
`IMPORT_STAR`	84	84	84	Pops a module and copies its public names into the namespace: `from module import *`
`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: re-raises an exception, returns or continues, as recorded
`POP_EXCEPT`	89	89	89	Removes an exception handler block; restores the exception state from the last three values popped
`STORE_NAME`	90	90	90	Stores TOS under the name at argument index of `co_names`, in the namespace
`DELETE_NAME`	91	91	91	Deletes that name from the namespace
`UNPACK_SEQUENCE`	92	92	92	Pops a sequence and pushes its argument-many items, with the first on top
`FOR_ITER`	93	93	93	TOS is an iterator. Pushes its next value, or pops it and jumps when it is finished (relative)
`UNPACK_EX`	94	94	94	Unpacks with a star target: the low byte of the argument is the count before the star, the high byte the count after
`STORE_ATTR`	95	95	95	`TOS.name = TOS1`; argument is an index in `co_names`
`DELETE_ATTR`	96	96	96	`del TOS.name`; argument is an index in `co_names`
`STORE_GLOBAL`	97	97	97	Pops TOS and stores it as a global; argument is an index in `co_names`
`DELETE_GLOBAL`	98	98	98	Deletes a global; argument is an index in `co_names`
`LOAD_CONST`	100	100	100	Pushes `co_consts[argument]`
`LOAD_NAME`	101	101	101	Pushes the value of the name at index of `co_names`
`BUILD_TUPLE`	102	102	102	Pops argument-many values, pushes a tuple of them
`BUILD_LIST`	103	103	103	Pops argument-many values, pushes a list of them
`BUILD_SET`	104	104	104	Pops argument-many values, pushes a set of them
`BUILD_MAP`	105	105	105	Pushes a dictionary. In 3.3 and 3.4 it is empty, pre-sized for argument-many entries. In 3.5 it holds argument-many pairs popped from the stack
`LOAD_ATTR`	106	106	106	`TOS = TOS.name`; argument is an index in `co_names`
`COMPARE_OP`	107	107	107	Pops two values, pushes the result of the comparison named in the comparison table
`IMPORT_NAME`	108	108	108	Imports the module named at index of `co_names`; TOS and TOS1 give `fromlist` and `level`; pushes the module
`IMPORT_FROM`	109	109	109	Pushes the attribute named at index of `co_names`, taken from the module in TOS, which stays
`JUMP_FORWARD`	110	110	110	Jumps forward by the argument (relative)
`JUMP_IF_FALSE_OR_POP`	111	111	111	If TOS is false, jumps and keeps it; otherwise pops it (absolute)
`JUMP_IF_TRUE_OR_POP`	112	112	112	If TOS is true, jumps and keeps it; otherwise pops it (absolute)
`JUMP_ABSOLUTE`	113	113	113	Jumps to the byte offset given by the argument (absolute)
`POP_JUMP_IF_FALSE`	114	114	114	Pops TOS and jumps if it is false (absolute)
`POP_JUMP_IF_TRUE`	115	115	115	Pops TOS and jumps if it is true (absolute)
`LOAD_GLOBAL`	116	116	116	Pushes the global named at index of `co_names`
`CONTINUE_LOOP`	119	119	119	Continues a loop because of a `continue` statement; the argument is the address of the loop’s `FOR_ITER` (absolute)
`SETUP_LOOP`	120	120	120	Pushes a block for a loop; it spans from the current instruction for a size of the argument (relative)
`SETUP_EXCEPT`	121	121	121	Pushes a `try` block for a `try`/`except`; the argument (relative) points to the first `except` block
`SETUP_FINALLY`	122	122	122	Pushes a `try` block for a `try`/`finally`; the argument (relative) points to the `finally` block
`LOAD_FAST`	124	124	124	Pushes local variable `co_varnames[argument]`
`STORE_FAST`	125	125	125	Pops TOS into local variable `co_varnames[argument]`
`DELETE_FAST`	126	126	126	Deletes local variable `co_varnames[argument]`
`RAISE_VARARGS`	130	130	130	Raises an exception: argument 0 re-raises, 1 raises TOS, 2 raises TOS1 with `__cause__` TOS
`CALL_FUNCTION`	131	131	131	Calls a callable: the argument holds the counts of positional and keyword arguments on the stack. Pushes the result
`MAKE_FUNCTION`	132	132	132	Pushes a new function, popping the qualified name, the code object and the values given by the argument
`BUILD_SLICE`	133	133	133	Pushes a slice made from 2 or 3 values, according to the argument
`MAKE_CLOSURE`	134	134	134	Like `MAKE_FUNCTION`, with a tuple of cells for the free variables at TOS2
`LOAD_CLOSURE`	135	135	135	Pushes the cell at this index: cells first, then free variables
`LOAD_DEREF`	136	136	136	Pushes the value of the cell at this index
`STORE_DEREF`	137	137	137	Pops TOS into the cell at this index
`DELETE_DEREF`	138	138	138	Empties the cell at this index
`CALL_FUNCTION_VAR`	140	140	140	As `CALL_FUNCTION`, with an iterable of extra positional arguments on the stack
`CALL_FUNCTION_KW`	141	141	141	As `CALL_FUNCTION`, with a mapping of extra keyword arguments on top of the stack
`CALL_FUNCTION_VAR_KW`	142	142	142	As `CALL_FUNCTION`, with both a mapping on top and an iterable of extra positional arguments
`SETUP_WITH`	143	143	143	Calls `__enter__()`, saves `__exit__`, pushes a `finally` block at the argument (relative) and the result of entering
`EXTENDED_ARG`	144	144	144	Supplies the top 16 bits of the next instruction’s argument
`LIST_APPEND`	145	145	145	`list.append(TOS1[-i], TOS)`, for list comprehensions; the list stays
`SET_ADD`	146	146	146	`set.add(TOS1[-i], TOS)`, for set comprehensions; the set stays
`MAP_ADD`	147	147	147	Adds TOS as key and TOS1 as value to the dictionary `i` places down, for dictionary comprehensions
`LOAD_CLASSDEREF`	–	148	148	Like `LOAD_DEREF`, but looks in the locals first; used in class bodies
`BUILD_LIST_UNPACK`	–	–	149	Pops argument-many iterables, pushes one list: `[x, y]`
`BUILD_MAP_UNPACK`	–	–	150	Pops argument-many mappings, pushes one dictionary: `{x, y}`
`BUILD_MAP_UNPACK_WITH_CALL`	–	–	151	The same for `f(x, y)`. The lowest byte of the argument is the count; the callable’s position is in the second byte
`BUILD_TUPLE_UNPACK`	–	–	152	Pops argument-many iterables, pushes one tuple: `(x, y)`
`BUILD_SET_UNPACK`	–	–	153	Pops argument-many iterables, pushes one set: `{x, y}`
`SETUP_ASYNC_WITH`	–	–	154	Sets up a `finally` block for `async with`; the argument is relative

COMPARE_OP arguments

Argument	Operator
0	`<`
1	`<=`
2	`==`
3	`!=`
4	`>`
5	`>=`
6	`in`
7	`not in`
8	`is`
9	`is not`
10	exception match
11	`BAD`

Function call arguments

CALL_FUNCTION, CALL_FUNCTION_VAR, CALL_FUNCTION_KW and CALL_FUNCTION_VAR_KW all use one argument: the low byte is the number of positional arguments, the high byte the number of keyword arguments. Keyword arguments are on top of the stack, each as a name then a value above it, with the positional arguments below them, then the callable. The iterable that CALL_FUNCTION_VAR and CALL_FUNCTION_VAR_KW add is above the keyword arguments in 3.3 and 3.4, and below them in 3.5.

MAKE_FUNCTION arguments

The argument packs three counts. MAKE_FUNCTION and MAKE_CLOSURE pop these values from the stack, then the code object at TOS1 and the qualified name at TOS.

Bits	Value
`argument & 0xFF`	Default values for positional parameters
`(argument >> 8) & 0xFF`	Pairs of a name and a default value for keyword-only parameters
`(argument >> 16) & 0x7FFF`	Annotation objects, followed by a tuple of parameter names if there are any

.PYC File Format – Instructions

Encoding

Opcodes

COMPARE_OP arguments

Function call arguments

MAKE_FUNCTION arguments