Python 2.1 and 2.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.

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: 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.

A jump’s argument is counted in bytes of co_code. JUMP_ABSOLUTE and CONTINUE_LOOP have an absolute target: the argument is the offset to go to. These count forward from the instruction after the jump, so the target is the jump’s own offset, plus 3, plus the argument: JUMP_FORWARD, JUMP_IF_FALSE, JUMP_IF_TRUE, FOR_LOOP, FOR_ITER, SETUP_LOOP, SETUP_EXCEPT, SETUP_FINALLY.

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

Opcode 86 in Python 2.2

Python 2.2’s Lib/dis.py names opcode 86 YIELD_STMT, while that release’s Include/opcode.h calls it YIELD_VALUE. It is the same opcode. The table below follows dis.py, as the explorer does.

Every opcode

Numbers are from Lib/dis.py at the 2.1.3 and 2.2.3 tags. A dash means the release does not have the opcode. Meanings follow Python’s bytecode documentation.

Name	2.1	2.2	Meaning
`STOP_CODE`	0	0	Marks the end of code for the compiler. The interpreter does not use it
`POP_TOP`	1	1	Removes TOS
`ROT_TWO`	2	2	Swaps the two top items
`ROT_THREE`	3	3	Lifts the second and third items one place and moves the top down to third
`DUP_TOP`	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
`UNARY_POSITIVE`	10	10	`TOS = +TOS`
`UNARY_NEGATIVE`	11	11	`TOS = -TOS`
`UNARY_NOT`	12	12	`TOS = not TOS`
`UNARY_CONVERT`	13	13	TOS = `TOS` (backticks: the value’s `repr`)
`UNARY_INVERT`	15	15	`TOS = ~TOS`
`BINARY_POWER`	19	19	`TOS = TOS1 ** TOS`
`BINARY_MULTIPLY`	20	20	`TOS = TOS1 * TOS`
`BINARY_DIVIDE`	21	21	`TOS = TOS1 / TOS`
`BINARY_MODULO`	22	22	`TOS = TOS1 % TOS`
`BINARY_ADD`	23	23	`TOS = TOS1 + TOS`
`BINARY_SUBTRACT`	24	24	`TOS = TOS1 - TOS`
`BINARY_SUBSCR`	25	25	`TOS = TOS1[TOS]`
`BINARY_FLOOR_DIVIDE`	–	26	`TOS = TOS1 // TOS`
`BINARY_TRUE_DIVIDE`	–	27	`TOS = TOS1 / TOS` when `from __future__ import division` is in effect
`INPLACE_FLOOR_DIVIDE`	–	28	In-place `TOS = TOS1 // TOS`
`INPLACE_TRUE_DIVIDE`	–	29	In-place `TOS = TOS1 / TOS` when `from __future__ import division` is in effect
`SLICE+0`	30	30	`TOS = TOS[:]`
`SLICE+1`	31	31	`TOS = TOS1[TOS:]`
`SLICE+2`	32	32	`TOS = TOS1[:TOS]`
`SLICE+3`	33	33	`TOS = TOS2[TOS1:TOS]`
`STORE_SLICE+0`	40	40	`TOS[:] = TOS1`
`STORE_SLICE+1`	41	41	`TOS1[TOS:] = TOS2`
`STORE_SLICE+2`	42	42	`TOS1[:TOS] = TOS2`
`STORE_SLICE+3`	43	43	`TOS2[TOS1:TOS] = TOS3`
`DELETE_SLICE+0`	50	50	`del TOS[:]`
`DELETE_SLICE+1`	51	51	`del TOS1[TOS:]`
`DELETE_SLICE+2`	52	52	`del TOS1[:TOS]`
`DELETE_SLICE+3`	53	53	`del TOS2[TOS1:TOS]`
`INPLACE_ADD`	55	55	In-place `TOS = TOS1 + TOS`
`INPLACE_SUBTRACT`	56	56	In-place `TOS = TOS1 - TOS`
`INPLACE_MULTIPLY`	57	57	In-place `TOS = TOS1 * TOS`
`INPLACE_DIVIDE`	58	58	In-place `TOS = TOS1 / TOS`
`INPLACE_MODULO`	59	59	In-place `TOS = TOS1 % TOS`
`STORE_SUBSCR`	60	60	`TOS1[TOS] = TOS2`
`DELETE_SUBSCR`	61	61	`del TOS1[TOS]`
`BINARY_LSHIFT`	62	62	`TOS = TOS1 << TOS`
`BINARY_RSHIFT`	63	63	`TOS = TOS1 >> TOS`
`BINARY_AND`	64	64	`TOS = TOS1 & TOS`
`BINARY_XOR`	65	65	`TOS = TOS1 ^ TOS`
`BINARY_OR`	66	66	`TOS = TOS1 \| TOS`
`INPLACE_POWER`	67	67	In-place `TOS = TOS1 ** TOS`
`GET_ITER`	–	68	`TOS = iter(TOS)`
`PRINT_EXPR`	70	70	The expression statement in interactive mode: removes TOS and prints it
`PRINT_ITEM`	71	71	Prints TOS, one per item of a `print` statement
`PRINT_NEWLINE`	72	72	Prints a new line. Ends a `print` statement that does not end with a comma
`PRINT_ITEM_TO`	73	73	As `PRINT_ITEM`, but prints the item below TOS to the file at TOS (`print >>f`)
`PRINT_NEWLINE_TO`	74	74	As `PRINT_NEWLINE`, on the file at TOS
`INPLACE_LSHIFT`	75	75	In-place `TOS = TOS1 << TOS`
`INPLACE_RSHIFT`	76	76	In-place `TOS = TOS1 >> TOS`
`INPLACE_AND`	77	77	In-place `TOS = TOS1 & TOS`
`INPLACE_XOR`	78	78	In-place `TOS = TOS1 ^ TOS`
`INPLACE_OR`	79	79	In-place `TOS = TOS1 \| TOS`
`BREAK_LOOP`	80	80	Ends a loop, for a `break` statement
`LOAD_LOCALS`	82	82	Pushes the local namespace. Used at the end of a class body
`RETURN_VALUE`	83	83	Returns TOS to the caller
`IMPORT_STAR`	84	84	Copies every name not starting with `_` from the module at TOS into the local namespace, then pops the module (`from m import *`)
`EXEC_STMT`	85	85	`exec TOS2, TOS1, TOS`. The compiler fills in missing arguments with `None`
`YIELD_STMT`	–	86	Pops TOS and yields it from a generator. See the note on opcode 86
`POP_BLOCK`	87	87	Removes one block from the block stack
`END_FINALLY`	88	88	Ends a `finally` clause. The interpreter re-raises the exception, returns or goes on, as it had recorded
`BUILD_CLASS`	89	89	Makes a class: TOS is the methods dictionary, TOS1 the tuple of base classes, TOS2 the name
`STORE_NAME`	90	90	`name = TOS`. The argument is an index into `co_names`
`DELETE_NAME`	91	91	`del name`. The argument is an index into `co_names`
`UNPACK_SEQUENCE`	92	92	Unpacks TOS into the given number of values, pushed right to left
`FOR_ITER`	–	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
`STORE_ATTR`	95	95	`TOS.name = TOS1`. The argument is an index into `co_names`
`DELETE_ATTR`	96	96	`del TOS.name`. The argument is an index into `co_names`
`STORE_GLOBAL`	97	97	As `STORE_NAME`, but stores a global
`DELETE_GLOBAL`	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	Pushes `co_consts[argument]`
`LOAD_NAME`	101	101	Pushes the value of `co_names[argument]`
`BUILD_TUPLE`	102	102	Pops the given number of items and pushes them as a tuple
`BUILD_LIST`	103	103	As `BUILD_TUPLE`, but makes a list
`BUILD_MAP`	104	104	Pushes an empty dictionary. The argument is ignored and set to zero by the compiler
`LOAD_ATTR`	105	105	Replaces TOS with `getattr(TOS, co_names[argument])`
`COMPARE_OP`	106	106	Compares TOS1 with TOS. The argument indexes the operators
`IMPORT_NAME`	107	107	Imports the module `co_names[argument]` and pushes it. The namespace is not changed; a following store does that
`IMPORT_FROM`	108	108	Loads the attribute `co_names[argument]` from the module at TOS and pushes it, for a following store
`JUMP_FORWARD`	110	110	Moves the byte counter on by the argument
`JUMP_IF_FALSE`	111	111	If TOS is false, moves the byte counter on by the argument. TOS is left on the stack
`JUMP_IF_TRUE`	112	112	If TOS is true, moves the byte counter on by the argument. TOS is left on the stack
`JUMP_ABSOLUTE`	113	113	Sets the byte counter to the argument
`FOR_LOOP`	114	114	Steps a `for` loop by the older method: TOS is the index and TOS1 the sequence. When the sequence is exhausted, jumps forward by the argument
`LOAD_GLOBAL`	116	116	Pushes the global `co_names[argument]`
`CONTINUE_LOOP`	119	119	Continues a loop, for a `continue` statement. The argument is the address to jump to
`SETUP_LOOP`	120	120	Pushes a loop block. The block is the argument’s size in bytes from the current instruction
`SETUP_EXCEPT`	121	121	Pushes a `try` block. The argument points to the first `except` block
`SETUP_FINALLY`	122	122	Pushes a `try` block. The argument points to the `finally` block
`LOAD_FAST`	124	124	Pushes the local variable `co_varnames[argument]`
`STORE_FAST`	125	125	Stores TOS into the local variable `co_varnames[argument]`
`DELETE_FAST`	126	126	Deletes the local variable `co_varnames[argument]`
`SET_LINENO`	127	127	Sets the current line number to the argument. See Line numbers
`RAISE_VARARGS`	130	130	Raises an exception. The argument is how many arguments the `raise` statement gave, at most three: the traceback at TOS2, the value at TOS1, the exception at TOS
`CALL_FUNCTION`	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
`MAKE_FUNCTION`	132	132	Pushes a new function. TOS is its code. The argument is how many default values lie below it
`BUILD_SLICE`	133	133	Pushes a slice. With argument 2 it is `slice(TOS1, TOS)`; with 3, `slice(TOS2, TOS1, TOS)`
`MAKE_CLOSURE`	134	134	Pushes a new function with a closure. TOS is its code, and the next items are the cells for its free variables. The argument is how many default values lie below the cells
`LOAD_CLOSURE`	135	135	Pushes the cell in the given slot of the cell and free variable storage
`LOAD_DEREF`	136	136	Pushes the object held by the cell in the given slot
`STORE_DEREF`	137	137	Stores TOS into the cell in the given slot
`CALL_FUNCTION_VAR`	140	140	As `CALL_FUNCTION`; TOS is the variable argument list
`CALL_FUNCTION_KW`	141	141	As `CALL_FUNCTION`; TOS is the keyword arguments dictionary
`CALL_FUNCTION_VAR_KW`	142	142	As `CALL_FUNCTION`; TOS is the keyword arguments dictionary, below it the variable argument tuple
`EXTENDED_ARG`	143	143	Gives the next instruction the high 16 bits of its argument

.PYC File Format – Instructions

Encoding

Arguments and jumps

Comparison operators

Opcode 86 in Python 2.2

Every opcode