{"id":749,"library":"bytecode","title":"Python Bytecode Generator and Modifier","description":"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.","status":"active","version":"0.17.0","language":"python","source_language":"en","source_url":"https://github.com/MatthieuDartiailh/bytecode","tags":["bytecode","compiler","AST","low-level","code-generation"],"install":[{"cmd":"pip install bytecode","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Runtime environment; requires Python 3.9 or newer.","package":"python","optional":false}],"imports":[{"symbol":"Bytecode","correct":"from bytecode import Bytecode"},{"symbol":"Instr","correct":"from bytecode import Instr"},{"symbol":"ConcreteBytecode","correct":"from bytecode import ConcreteBytecode"},{"symbol":"ControlFlowGraph","correct":"from bytecode import ControlFlowGraph"}],"quickstart":{"code":"from bytecode import Instr, Bytecode\n\n# Create bytecode for print('Hello World!')\nbytecode_obj = Bytecode([\n    Instr('LOAD_GLOBAL', (True, 'print')), # Load the global 'print' function\n    Instr('LOAD_CONST', 'Hello World!'), # Load the string 'Hello World!'\n    Instr('CALL', 1), # Call 'print' with 1 argument\n    Instr('POP_TOP'), # Pop the return value (None) from the stack\n    Instr('LOAD_CONST', None), # Load None\n    Instr('RETURN_VALUE') # Return None\n])\n\n# Convert the bytecode object to a CPython code object\ncode = bytecode_obj.to_code()\n\n# Execute the generated code\nexec(code)","lang":"python","description":"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!'."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"All versions of bytecode (inherent to CPython's design)"},{"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.","message":"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`).","severity":"breaking","affected_versions":"0.17.0 and newer (from older versions)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-05-12T18:33:33.237Z","next_check":"2026-06-27T00:00:00.000Z","problems":[{"fix":"Install the library using pip: `pip install bytecode`","cause":"The 'bytecode' library is not installed in your Python environment or the Python interpreter cannot find it in its search path.","error":"ModuleNotFoundError: No module named 'bytecode'"},{"fix":"Upgrade the 'bytecode' library to a version 0.14.0 or newer: `pip install --upgrade bytecode`","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.","error":"AttributeError: module 'bytecode' has no attribute 'BinaryOp'"},{"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`","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.","error":"TypeError: operation LOAD_ATTR argument must be a str, got tuple"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":60,"quickstart_tag":"reviewed","pypi_latest":"0.17.0","cli_name":"","install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","installed_version":null,"pypi_latest":"0.17.0","is_stale":null,"results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"bytecode","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.05,"mem_mb":1.9,"disk_size":"18.1M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"bytecode","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":1.9,"disk_size":"18.1M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"bytecode","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":null,"install_time_s":1.5,"import_time_s":0.03,"mem_mb":1.9,"disk_size":"19M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"bytecode","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.03,"mem_mb":1.9,"disk_size":"19M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"bytecode","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.08,"mem_mb":2.2,"disk_size":"20.0M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"bytecode","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.09,"mem_mb":2.2,"disk_size":"20.0M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"bytecode","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":null,"install_time_s":1.6,"import_time_s":0.07,"mem_mb":2.2,"disk_size":"20M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"bytecode","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.07,"mem_mb":2.2,"disk_size":"20M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"bytecode","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.07,"mem_mb":2,"disk_size":"11.8M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"bytecode","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.07,"mem_mb":2,"disk_size":"11.8M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"bytecode","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":null,"install_time_s":1.4,"import_time_s":0.07,"mem_mb":2,"disk_size":"12M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"bytecode","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.08,"mem_mb":2,"disk_size":"12M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"bytecode","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.07,"mem_mb":2.4,"disk_size":"11.6M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"bytecode","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.07,"mem_mb":2.4,"disk_size":"11.5M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"bytecode","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":null,"install_time_s":1.6,"import_time_s":0.06,"mem_mb":2.2,"disk_size":"12M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"bytecode","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.07,"mem_mb":2.2,"disk_size":"12M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"bytecode","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":2.3,"disk_size":"17.9M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"bytecode","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.05,"mem_mb":2.3,"disk_size":"17.9M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"bytecode","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":null,"install_time_s":1.8,"import_time_s":0.04,"mem_mb":2.3,"disk_size":"18M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"bytecode","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":2.3,"disk_size":"18M"}]},"quickstart_checks":{"last_tested":"2026-04-24","tag":"reviewed","tag_description":"minor failures on some runtimes or slightly older test data","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":0},{"runtime":"python:3.11-slim","exit_code":0},{"runtime":"python:3.12-alpine","exit_code":0},{"runtime":"python:3.12-slim","exit_code":0},{"runtime":"python:3.13-alpine","exit_code":0},{"runtime":"python:3.13-slim","exit_code":0},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}