Install & Compatibility
Where this runs
tested against v0.17.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.060s · 18.1MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.6s · import 0.056s · 19MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Bytecode
✓ from bytecode import Bytecode
Instr
✓ from bytecode import Instr
ConcreteBytecode
✓ from bytecode import ConcreteBytecode
ControlFlowGraph
✓ from bytecode import ControlFlowGraph
This quickstart demonstrates how to create a simple `Bytecode` object using `Instr` instances, convert it to a standard Python code object, and then execute it to print 'Hello World!'.
from bytecode import Instr, Bytecode
# Create bytecode for print('Hello World!')
bytecode_obj = Bytecode([
Instr('LOAD_GLOBAL', (True, 'print')), # Load the global 'print' function
Instr('LOAD_CONST', 'Hello World!'), # Load the string 'Hello World!'
Instr('CALL', 1), # Call 'print' with 1 argument
Instr('POP_TOP'), # Pop the return value (None) from the stack
Instr('LOAD_CONST', None), # Load None
Instr('RETURN_VALUE') # Return None
])
# Convert the bytecode object to a CPython code object
code = bytecode_obj.to_code()
# Execute the generated code
exec(code)
Debug
Known issues
breakingThe structure of Python bytecode is an internal implementation detail of CPython and can change significantly between major Python versions. While `bytecode` aims to abstract this, code built for one Python version may behave differently or break on another due to underlying CPython changes, especially when generating bytecode that isn't fully generic.fixAlways test bytecode generation and modification across all target Python versions. Utilize `bytecode`'s version-aware features and abstractions where possible, rather than relying on raw opcode values specific to one Python version.
affects: All versions of bytecode (inherent to CPython's design)
breakingThe `bytecode` library's API has undergone changes to accommodate new CPython bytecode formats and features, particularly with Python 3.11, 3.13, and 3.14 support. For example, `BaseInstr` was removed and `Instr` became the base class in 0.17.0, and new enums are now used for certain opcode arguments (e.g., `BINARY_OP`, `CONVERT_VALUE`).fixReview the `bytecode` changelog for each major release, especially when upgrading or targeting newer Python versions. Adapt your code to use the latest API, such as replacing `BaseInstr` with `Instr` and using enum members for opcode arguments where required.
affects: 0.17.0 and newer (from older versions)
gotchaDirect manipulation of bytecode is a low-level operation and requires a deep understanding of the Python Virtual Machine's stack-based execution model, opcode semantics, and operand types. Misinterpreting stack effects or opcode arguments can lead to incorrect or crashing bytecode.fixConsult the `dis` module's documentation for the target Python version to understand opcode behavior. Start with simple bytecode structures and progressively build complexity, frequently testing the generated code. Use `dis.dis()` on simple Python functions to see how CPython compiles them into bytecode as a reference.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'bytecode'
The 'bytecode' library is not installed in your Python environment or the Python interpreter cannot find it in its search path.
fixInstall the library using pip: `pip install bytecode`
AttributeError: module 'bytecode' has no attribute 'BinaryOp'
This error typically occurs when using an older version of the 'bytecode' library that does not include the 'BinaryOp' enum, which was introduced in version 0.14.0.
fixUpgrade the 'bytecode' library to a version 0.14.0 or newer: `pip install --upgrade bytecode`
TypeError: operation LOAD_ATTR argument must be a str, got tuple
This `TypeError` indicates an incompatibility between the 'bytecode' library version and the Python version being used (e.g., Python 3.12), where certain bytecode operations expect a string argument but receive a tuple due to changes in how bytecode is handled.
fixEnsure you are using a version of 'bytecode' that is compatible with your Python interpreter version. Upgrading 'bytecode' often resolves such issues: `pip install --upgrade bytecode`
Upgrade
Version history
0.19.0latest on PyPI · released Aug 21, 2026
Audit
Dependencies
pythonrequiredRuntime environment; requires Python 3.9 or newer.