Python Bytecode Generator and Modifier

0.17.0 verified Tue May 12 auth: no python install: verified quickstart: reviewed

The `bytecode` library is a Python module designed to generate, analyze, and modify Python bytecode. It provides an abstract representation of bytecode that can be manipulated and then converted back into executable code objects. Currently at version 0.17.0, it is actively maintained with a regular release cadence, often introducing support for new Python versions and associated bytecode changes.

pip install bytecode

Common errors

error ModuleNotFoundError: No module named 'bytecode' ↓

cause The 'bytecode' library is not installed in your Python environment or the Python interpreter cannot find it in its search path.

fix

Install the library using pip: pip install bytecode

error AttributeError: module 'bytecode' has no attribute 'BinaryOp' ↓

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

fix

Upgrade the 'bytecode' library to a version 0.14.0 or newer: pip install --upgrade bytecode

error TypeError: operation LOAD_ATTR argument must be a str, got tuple ↓

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

fix

Ensure 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

Warnings

breaking The 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. ↓

fix Always 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.

breaking The `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`). ↓

fix Review 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.

gotcha Direct 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. ↓

fix Consult 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.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - 0.05s 18.1M

3.10 alpine (musl) - - 0.04s 18.1M

3.10 slim (glibc) wheel 1.5s 0.03s 19M

3.10 slim (glibc) - - 0.03s 19M

3.11 alpine (musl) wheel - 0.08s 20.0M

3.11 alpine (musl) - - 0.09s 20.0M

3.11 slim (glibc) wheel 1.6s 0.07s 20M

3.11 slim (glibc) - - 0.07s 20M

3.12 alpine (musl) wheel - 0.07s 11.8M

3.12 alpine (musl) - - 0.07s 11.8M

3.12 slim (glibc) wheel 1.4s 0.07s 12M

3.12 slim (glibc) - - 0.08s 12M

3.13 alpine (musl) wheel - 0.07s 11.6M

3.13 alpine (musl) - - 0.07s 11.5M

3.13 slim (glibc) wheel 1.6s 0.06s 12M

3.13 slim (glibc) - - 0.07s 12M

3.9 alpine (musl) wheel - 0.04s 17.9M

3.9 alpine (musl) - - 0.05s 17.9M

3.9 slim (glibc) wheel 1.8s 0.04s 18M

3.9 slim (glibc) - - 0.04s 18M

Imports

Bytecode
```
from bytecode import Bytecode
```
Instr
```
from bytecode import Instr
```
ConcreteBytecode
```
from bytecode import ConcreteBytecode
```
ControlFlowGraph
```
from bytecode import ControlFlowGraph
```

Quickstart reviewed last tested: 2026-04-24

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)