Python 3.13 .pyc files: instructions

co_code holds the instructions of a code object. This page lists every instruction a Python 3.13 .pyc file can hold, with its number, as Python 3.13’s own opcode module gives them. Pseudo-instructions, the specialised forms the interpreter makes while it runs and the INSTRUMENTED_* forms used for monitoring are left out: they never appear in a file.

Encoding

co_code is a sequence of 16-bit code units, each one byte of opcode and one byte of argument. Every instruction occupies one code unit, plus any inline cache units after it. An instruction with no argument still has the argument byte; it is zero, and it is ignored.

The numbers are generated from CPython’s instruction definitions. Instructions without an argument are numbered first, in alphabetical order, from 1 to 44, with 17 kept as RESERVED. Those with an argument follow, also alphabetically, from 45 to 118, and RESUME is 149. opcode.hasarg lists the ones with an argument. opcode.HAVE_ARGUMENT is 44, but it is not a usable threshold: WITH_EXCEPT_START, 44, takes no argument.

EXTENDED_ARG widens an argument. It goes before the instruction, and its argument becomes the higher byte: up to three prefixes give the following instruction a 32-bit argument.

Inline caches

Some instructions are followed by a fixed number of 16-bit cache entries. The interpreter fills them in while the program runs, to specialise the instruction. In a file they are all zero. They are part of the instruction that precedes them: dis hides them unless asked, as CACHE instructions. A reader must step over them.

Instruction	Cache units	Fields, in units
`BINARY_OP`	1	counter 1
`BINARY_SUBSCR`	1	counter 1
`CALL`	3	counter 1, func_version 2
`COMPARE_OP`	1	counter 1
`CONTAINS_OP`	1	counter 1
`FOR_ITER`	1	counter 1
`JUMP_BACKWARD`	1	counter 1
`LOAD_ATTR`	9	counter 1, version 2, keys_version 2, descr 4
`LOAD_GLOBAL`	4	counter 1, index 1, module_keys_version 1, builtin_keys_version 1
`LOAD_SUPER_ATTR`	1	counter 1
`POP_JUMP_IF_FALSE`	1	counter 1
`POP_JUMP_IF_NONE`	1	counter 1
`POP_JUMP_IF_NOT_NONE`	1	counter 1
`POP_JUMP_IF_TRUE`	1	counter 1
`SEND`	1	counter 1
`STORE_ATTR`	4	counter 1, version 2, index 1
`STORE_SUBSCR`	1	counter 1
`TO_BOOL`	3	counter 1, version 2
`UNPACK_SEQUENCE`	1	counter 1

Jump arguments

Every jump is relative. Its argument counts 16-bit code units, not bytes, from the point just after the instruction, past its inline caches. In bytes:

target = offset + 2 + 2 × caches ± 2 × argument

The sign is minus for JUMP_BACKWARD, which has one cache unit, and JUMP_BACKWARD_NO_INTERRUPT, which has none. It is plus for every other jump: JUMP_FORWARD, and the four POP_JUMP_IF_* instructions, FOR_ITER and SEND, which each have one cache unit. For example, JUMP_BACKWARD 5 at offset 12 goes to 12 + 2 + 2 − 10 = 6.

Every instruction

The argument, where one is used, is called arg. Local slot numbers index co_localsplusnames; a name index goes into co_names and a constant index into co_consts.

Name	Number	Meaning
`BEFORE_ASYNC_WITH`	1	Takes `__aenter__` and `__aexit__` from the top; pushes `__aexit__`, then the result of calling `__aenter__()`
`BEFORE_WITH`	2	Pushes the context manager’s `__exit__`, calls `__enter__()`, pushes its result
`BINARY_OP`	45	Pops two values, pushes the result. arg is the operator
`BINARY_SLICE`	4	Pops end, start and container; pushes `container[start:end]`
`BINARY_SUBSCR`	5	Pops key and container; pushes `container[key]`
`BUILD_CONST_KEY_MAP`	46	Pops a tuple of keys, then arg values; pushes a dictionary
`BUILD_LIST`	47	Pops arg items, pushes a list
`BUILD_MAP`	48	Pops 2 × arg items, pushes a dictionary of arg entries
`BUILD_SET`	49	Pops arg items, pushes a set
`BUILD_SLICE`	50	arg is 2 or 3. Pops start and end, and step if 3; pushes a slice
`BUILD_STRING`	51	Pops arg strings and pushes them joined
`BUILD_TUPLE`	52	Pops arg items, pushes a tuple
`CACHE`	0	Not a real instruction. Opcode 0 is the value of a zeroed inline cache entry
`CALL`	53	Calls with arg positional arguments. Below them are the callable and then `self` or NULL; `self` is not counted in arg. Pops them all and pushes the result
`CALL_FUNCTION_EX`	54	Calls with an iterable of positional arguments, and a keyword mapping on top when arg bit 0 is set. Below them are the callable and a NULL
`CALL_INTRINSIC_1`	55	Replaces the top of the stack with the result of an intrinsic selected by arg
`CALL_INTRINSIC_2`	56	Pops two values and pushes the result of an intrinsic selected by arg
`CALL_KW`	57	Like `CALL`, with a tuple of keyword names on top of the stack, naming the last arguments. arg counts positional and named arguments
`CHECK_EG_MATCH`	6	For `except*`: splits the exception group below the top by the type on top; pushes the rest and the match
`CHECK_EXC_MATCH`	7	Pops the type on top; pushes whether the exception below matches it
`CLEANUP_THROW`	8	If the top is a `StopIteration`, pops three values and pushes `None` and the exception’s value; otherwise re-raises it. Handles an exception from `throw()` or `close()`
`COMPARE_OP`	58	Pops two values, pushes the comparison. See comparison operators for the argument
`CONTAINS_OP`	59	Pops two values, pushes `in`, or `not in` if arg is 1
`CONVERT_VALUE`	60	Pops a value, pushes `str` (arg 1), `repr` (2) or `ascii` (3) of it, for an f-string
`COPY`	61	Pushes a copy of the item arg places down, counting the top as 1
`COPY_FREE_VARS`	62	Copies arg free variables from the closure into the frame
`DELETE_ATTR`	63	Pops an object; `del obj.name`. arg is a name index
`DELETE_DEREF`	64	Empties the cell in slot arg
`DELETE_FAST`	65	Deletes the local in slot arg
`DELETE_GLOBAL`	66	Deletes a global. arg is a name index
`DELETE_NAME`	67	Deletes a name. arg is a name index
`DELETE_SUBSCR`	9	Pops key and container; `del container[key]`
`DICT_MERGE`	68	Like `DICT_UPDATE`, but raises an error on a duplicate key
`DICT_UPDATE`	69	Pops a mapping and adds it to the dictionary arg places down
`END_ASYNC_FOR`	10	Ends an `async for`: pops the iterable and the exception; re-raises it unless it is `StopAsyncIteration`
`END_FOR`	11	Removes the top value. The compiler puts it, and a `POP_TOP`, at the end of each `for` loop; `FOR_ITER` jumps past both when the loop ends
`END_SEND`	12	Removes the item below the top, when a sub-generator has finished
`ENTER_EXECUTOR`	70	Only exists at run time: hands over to code made by the optimiser. Not expected in a file
`EXIT_INIT_CHECK`	13	Pops the value `__init__` returned and raises `TypeError` unless it is `None`. Used by the interpreter internally
`EXTENDED_ARG`	71	Gives the next instruction’s argument more high bits
`FORMAT_SIMPLE`	14	Pops a value, pushes `value.__format__("")`, for an f-string
`FORMAT_WITH_SPEC`	15	Pops a spec and a value, pushes `value.__format__(spec)`, for an f-string
`FOR_ITER`	72	Calls `__next__()` on the iterator on top and pushes the value, leaving the iterator below it. When the iterator is exhausted, pops it and jumps forward by arg, and then over the `END_FOR` and `POP_TOP` found there
`GET_AITER`	16	Replaces the top with `__aiter__()` of it
`GET_ANEXT`	18	Pushes an awaitable of `__anext__()` of the top
`GET_AWAITABLE`	73	Replaces the top with an awaitable. arg is 1 after `__aenter__`, 2 after `__aexit__`, else 0
`GET_ITER`	19	Replaces the top with `iter()` of it
`GET_LEN`	20	Pushes `len()` of the top
`GET_YIELD_FROM_ITER`	21	Leaves a generator or coroutine on top unchanged; replaces anything else with `iter()` of it
`IMPORT_FROM`	74	Pushes an attribute of the module on top. arg is a name index
`IMPORT_NAME`	75	Pops level and fromlist; pushes the imported module. arg is a name index
`INTERPRETER_EXIT`	22	Leaves the interpreter loop. Used only by the interpreter’s internal frames
`IS_OP`	76	Pops two values, pushes `is`, or `is not` if arg is 1
`JUMP_BACKWARD`	77	Jumps back by arg and checks for interrupts
`JUMP_BACKWARD_NO_INTERRUPT`	78	Jumps back by arg without checking for interrupts
`JUMP_FORWARD`	79	Jumps forward by arg
`LIST_APPEND`	80	Pops an item and appends it to the list arg places down
`LIST_EXTEND`	81	Pops an iterable and extends the list arg places down
`LOAD_ASSERTION_ERROR`	23	Pushes `AssertionError`
`LOAD_ATTR`	82	Replaces the top with an attribute of it. The name index is arg `>> 1`. If bit 0 is set it loads for a call: it pushes the unbound method and then the object, which the call passes as `self`, or the attribute and then NULL
`LOAD_BUILD_CLASS`	24	Pushes the function `builtins.__build_class__`, which a following call uses to make a class
`LOAD_CONST`	83	Pushes a constant. arg is a constant index
`LOAD_DEREF`	84	Pushes the object in the cell in slot arg
`LOAD_FAST`	85	Pushes the local in slot arg. The compiler uses it only where the local is known to be set, and also to push a cell when it builds a closure
`LOAD_FAST_AND_CLEAR`	86	Pushes the local in slot arg, or NULL if it is not set, and clears the slot. Used to save a variable an inlined comprehension reuses
`LOAD_FAST_CHECK`	87	Pushes the local in slot arg, or raises `UnboundLocalError` if it is not set
`LOAD_FAST_LOAD_FAST`	88	Pushes two locals: slots arg `>> 4` and arg `& 15`
`LOAD_FROM_DICT_OR_DEREF`	89	Pops a mapping and looks up the name of slot arg in it; falls back to the cell. Used in class bodies
`LOAD_FROM_DICT_OR_GLOBALS`	90	Pops a mapping and looks up a name in it, then in globals and builtins. arg is a name index
`LOAD_GLOBAL`	91	Pushes a global. The name index is arg `>> 1`; if bit 0 is set, a NULL is pushed after it, for a call
`LOAD_LOCALS`	25	Pushes the locals dictionary
`LOAD_NAME`	92	Pushes a name found in locals, globals or builtins. arg is a name index
`LOAD_SUPER_ATTR`	93	Pops `self`, the class and `super`; loads an attribute as `super()` does. The name index is arg `>> 2`; bit 0 asks for a method load; bit 1 marks the two-argument `super`
`MAKE_CELL`	94	Makes a new cell in slot arg, holding the slot’s value if it has one
`MAKE_FUNCTION`	26	Replaces the code object on top with a function made from it. It takes no argument; `SET_FUNCTION_ATTRIBUTE` adds defaults, annotations and the closure
`MAP_ADD`	95	Pops a value and key, stores them in the dictionary arg places down
`MATCH_CLASS`	96	Pops the keyword names, class and subject; pushes a tuple of attributes, or `None`. arg is the number of positional sub-patterns
`MATCH_KEYS`	27	The top is a tuple of keys, the item below a mapping. Pushes a tuple of the values, or `None`
`MATCH_MAPPING`	28	Pushes whether the top is a mapping
`MATCH_SEQUENCE`	29	Pushes whether the top is a sequence and not text or bytes
`NOP`	30	Does nothing
`POP_EXCEPT`	31	Pops a value and uses it to restore the exception state
`POP_JUMP_IF_FALSE`	97	Pops the top, which must be a `bool`; if false, jumps forward by arg
`POP_JUMP_IF_NONE`	98	Pops the top; if `None`, jumps forward by arg
`POP_JUMP_IF_NOT_NONE`	99	Pops the top; if not `None`, jumps forward by arg
`POP_JUMP_IF_TRUE`	100	Pops the top, which must be a `bool`; if true, jumps forward by arg
`POP_TOP`	32	Pops and discards the top
`PUSH_EXC_INFO`	33	Pops a value, pushes the current exception, pushes the value back
`PUSH_NULL`	34	Pushes NULL, for the calling sequence
`RAISE_VARARGS`	101	Raises: arg 0 re-raises, 1 raises the top, 2 raises the item below the top with the top as its cause
`RERAISE`	102	Pops the exception on top and re-raises it. If arg is nonzero, first sets `f_lasti` from the offset found arg places below the exception
`RESERVED`	17	A reserved number. Executing it is an interpreter error
`RESUME`	149	No visible effect; a point for tracing, debugging and optimisation checks. arg says where it is
`RETURN_CONST`	103	Returns a constant. arg is a constant index
`RETURN_GENERATOR`	35	Makes a generator, coroutine or async generator from the frame and returns it
`RETURN_VALUE`	36	Returns the top of the stack
`SEND`	104	Sends the top value into the sub-generator below it, for `yield from` and `await`, and replaces the top with what it yields. When the sub-generator finishes, it jumps forward by arg
`SETUP_ANNOTATIONS`	37	Makes `__annotations__` an empty dictionary in the locals, if it is missing
`SET_ADD`	105	Pops an item and adds it to the set arg places down
`SET_FUNCTION_ATTRIBUTE`	106	Pops a function and a value below it, sets one attribute of the function selected by arg, and pushes the function back
`SET_UPDATE`	107	Pops an iterable and adds its items to the set arg places down
`STORE_ATTR`	108	Pops an object and a value; sets the attribute. arg is a name index
`STORE_DEREF`	109	Pops a value into the cell in slot arg
`STORE_FAST`	110	Pops a value into the local in slot arg
`STORE_FAST_LOAD_FAST`	111	Pops a value into slot arg `>> 4`, then pushes the local in slot arg `& 15`
`STORE_FAST_STORE_FAST`	112	Pops two values into slots arg `>> 4` and arg `& 15`
`STORE_GLOBAL`	113	Pops a value into a global. arg is a name index
`STORE_NAME`	114	Pops a value into a name. arg is a name index
`STORE_SLICE`	38	Pops end, start, container and value; `container[start:end] = value`
`STORE_SUBSCR`	39	Pops key, container and value; `container[key] = value`
`SWAP`	115	Swaps the top with the item arg places down, counting the top as 1
`TO_BOOL`	40	Replaces the top with `bool()` of it
`UNARY_INVERT`	41	Replaces the top with `~` of it
`UNARY_NEGATIVE`	42	Replaces the top with `-` of it
`UNARY_NOT`	43	Replaces the top, which must be a `bool`, with `not` of it
`UNPACK_EX`	116	Unpacks the top with a starred target. The low byte of arg is the count before the list, and the high byte the count after it
`UNPACK_SEQUENCE`	117	Replaces the top with its arg items, pushed right to left
`WITH_EXCEPT_START`	44	Calls the `__exit__` function below the exception on top, for `with`
`YIELD_VALUE`	118	Pops the top and yields it. arg is 1 when it is part of a `yield from` or `await`, otherwise 0

LOAD_CLOSURE is not in the table: in Python 3.13 it is a pseudo-instruction that the compiler writes as LOAD_FAST.

Comparison operators

COMPARE_OP’s argument holds the index of the operator above bit 5, arg >> 5. Bit 4, arg & 16, asks for the result to be converted to bool; the compiler sets it when the comparison feeds a conditional jump. The low four bits are a mask of the outcomes that make the comparison true: 1 unordered, 2 less, 4 greater, 8 equal. The interpreter’s specialised forms of the instruction use the mask; the operator index alone gives the meaning.

Index	Operator	Mask
0	`<`	2
1	`<=`	10
2	`==`	8
3	`!=`	7
4	`>`	4
5	`>=`	12

For example, a == b compiles to COMPARE_OP 72: index 2 and mask 8. In if a < b: it is COMPARE_OP 18: index 0, bit 4 for bool, and mask 2.

BINARY_OP operators

arg	Operator	arg	Operator
0	`+`	13	`+=`
1	`&`	14	`&=`
2	`//`	15	`//=`
3	`<<`	16	`<<=`
4	`@`	17	`@=`
5	`*`	18	`*=`
6	`%`	19	`%=`
7	`\|`	20	`\|=`
8	`**`	21	`**=`
9	`>>`	22	`>>=`
10	`-`	23	`-=`
11	`/`	24	`/=`
12	`^`	25	`^=`

Intrinsics

CALL_INTRINSIC_1:

arg	Name	Does
0	`INTRINSIC_1_INVALID`	Not valid
1	`INTRINSIC_PRINT`	Prints the argument to standard output, in the REPL
2	`INTRINSIC_IMPORT_STAR`	`import *` from the module object given, into the local namespace
3	`INTRINSIC_STOPITERATION_ERROR`	Turns a `StopIteration` (or, in an async generator, `StopAsyncIteration`) that escapes a generator or coroutine into a `RuntimeError`
4	`INTRINSIC_ASYNC_GEN_WRAP`	Wraps an async generator value
5	`INTRINSIC_UNARY_POSITIVE`	Unary `+`
6	`INTRINSIC_LIST_TO_TUPLE`	Converts a list to a tuple
7	`INTRINSIC_TYPEVAR`	Creates a `TypeVar`
8	`INTRINSIC_PARAMSPEC`	Creates a `ParamSpec`
9	`INTRINSIC_TYPEVARTUPLE`	Creates a `TypeVarTuple`
10	`INTRINSIC_SUBSCRIPT_GENERIC`	`typing.Generic` subscripted with the argument
11	`INTRINSIC_TYPEALIAS`	Creates a `TypeAliasType`, for the `type` statement

CALL_INTRINSIC_2:

arg	Name	Does
0	`INTRINSIC_2_INVALID`	Not valid
1	`INTRINSIC_PREP_RERAISE_STAR`	Computes the exception group to raise from `try`–`except*`
2	`INTRINSIC_TYPEVAR_WITH_BOUND`	Creates a `TypeVar` with a bound
3	`INTRINSIC_TYPEVAR_WITH_CONSTRAINTS`	Creates a `TypeVar` with constraints
4	`INTRINSIC_SET_FUNCTION_TYPE_PARAMS`	Sets a function’s `__type_params__`
5	`INTRINSIC_SET_TYPEPARAM_DEFAULT`	Sets a type parameter’s default

Function attributes

The argument of SET_FUNCTION_ATTRIBUTE is one of these values, saying which attribute the value below the function sets.

arg	Value
0x01	Tuple of defaults for positional parameters
0x02	Dictionary of keyword-only defaults
0x04	Tuple of strings holding parameter annotations
0x08	Tuple of cells for free variables, the closure

RESUME argument

Bits	Meaning
0–1	Where the `RESUME` is: 0 the start of a function or module; 1 after a `yield`; 2 after a `yield from`; 3 after an `await`
2	Set when the `RESUME` is at except-depth 1

.PYC File Format – Instructions