Registry / serialization / xdis
library6.3.0pypypi✓ verified 89d ago

xdis is a Python library that provides a cross-version byte-code disassembler and marshal routines. It enables the inspection and manipulation of Python bytecode across a wide range of Python versions, from 1.0 up to 3.15+. The current version is 6.3.0, and it maintains an active release cadence, frequently updating with support for new Python versions and their respective bytecode changes.

pip install xdis
INSTALL
IMPORT
SIG · XDIS
X
xdis
serializationpythonv6.3.0
Install
1.9s avg
Import
172ms
Disk
19MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.9–3.13
musl
3.9–3.13
Install & Compatibility
Where this runs
tested against v6.3.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
musl
py 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.179s · 20.7MB
glibc
py 3.10–3.920 runs
installs and imports cleanly · install 1.9s · import 0.166s · 21MB
19MB installed
● package 19MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Bytecode
✓ from xdis.std import Bytecode
For a drop-in replacement of Python's built-in `dis.Bytecode` for cross-version analysis.
load_bytecode
✓ from xdis import load
To load bytecode from a .pyc file for a specific Python version.
disassemble
✓ from xdis.bytecode import disassemble
To directly disassemble bytecode objects.

This quickstart demonstrates how to use `xdis.std.Bytecode` as a drop-in replacement for the standard library's `dis.Bytecode` to inspect a Python function's bytecode. While `xdis` excels at disassembling bytecode from *different* Python versions, this example focuses on its core disassembler functionality. For advanced cross-version loading from `.pyc` files, users should refer to `xdis.load` functions.

import marshal import types from xdis.std import Bytecode def example_function(): a = 10 b = 'hello' if a > 5: print(b) return a # Get the code object of the function code_obj = example_function.__code__ # Disassemble using xdis.std.Bytecode (similar to stdlib dis) print(f"\nDisassembly for Python {code_obj.co_firstlineno} via xdis.std:") for instr in Bytecode(code_obj): print(instr) # Example of loading bytecode from a marshal.dumps() output (simulated .pyc content) # For true cross-version loading, you'd use xdis.load.load_bytecode_from_file # or xdis.load.load_bytecode_from_cstring to specify the Python magic number. def mock_marshal_loader(code_obj, python_version): # This is a simplified example; xdis.load handles actual magic numbers/versions # The real power is in loading *other* Python versions' bytecode. # For simplicity here, we'll just demonstrate disassembling a marshalled object. marshalled_code = marshal.dumps(code_obj) return marshalled_code marshalled_bytes = mock_marshal_loader(code_obj, (3, 9)) # Simulate Python 3.9 bytecode try: # To truly demonstrate xdis's cross-version capability, you'd load a .pyc file # generated by a *different* Python version than the one running this code. # For this example, we'll just show disassembling an arbitrary code object. # For actual cross-version loading, investigate xdis.load functions. print(f"\nDisassembly of a marshalled code object (Python {code_obj.co_firstlineno}):") # Note: For actual different Python versions, you'd need the specific magic number # and potentially xdis.load.load_bytecode_from_cstring or file-based loaders. # We'll re-disassemble the current code_obj for a runnable example. from xdis.bytecode import disassemble disassemble(code_obj) except Exception as e: print(f"Could not fully demonstrate cross-version load in quickstart due to complexity: {e}")
Debug
Known issues
breakingVersion 6.1.0 introduced major API changes, particularly affecting how disassembly options are specified (e.g., via `--format` on the `pydisasm` command-line utility) and new output formats like 'extended' or 'bytes'. Code written for previous versions may need updates.
fix
Review the `pydisasm -h` output and `xdis` documentation for updated API calls and format options. Adjust programmatic calls to `xdis` functions to match the new API.
affects: >=6.1.0
gotchaInstalling `xdis` via `pip install xdis` is primarily for Python 3.11 and newer. For older Python versions (e.g., 2.x, 3.0-3.10), you must manually download specific tarballs or wheels from the GitHub Releases page that are pre-compiled for those Python versions. Installing the generic package on older Python versions may lead to unexpected behavior or `ModuleNotFoundError` if dependencies are not correctly resolved or specific bytecode definitions are missing.
fix
For Python < 3.11, navigate to the `xdis` GitHub releases page and download the appropriate `xdis_X-x.y.z.tar.gz` or `.whl` file corresponding to your exact Python interpreter version. Install it manually using `pip install <downloaded_file>`. Ensure the Python environment you are installing into matches the target version of the `xdis` distribution.
affects: <6.3.0 (for pip install behavior), <3.11 Python interpreter
gotchaThe `MAKE_FUNCTION` opcode's formatting and behavior changed significantly in Python 3.11 compared to Python 3.6. `xdis` versions 6.1.7 and later include adjustments to handle these differences, but older `xdis` versions might produce incorrect or confusing disassembly output for Python 3.11 bytecode, especially around function creation.
fix
Upgrade to `xdis` version 6.1.7 or newer to ensure correct `MAKE_FUNCTION` formatting and improved marshalling routines for Python 3.11+ bytecode.
affects: <6.1.7 (when disassembling Python 3.6 or 3.11+ bytecode)
gotchaAn O(n^2) performance issue was identified and fixed in `xdis` version 6.1.7, specifically affecting the handling of exceptions in Python 3.11+. Users disassembling large codebases or complex exception structures with `xdis` versions prior to 6.1.7 on a Python 3.11+ interpreter may experience significant slowdowns.
fix
Upgrade to `xdis` version 6.1.7 or newer to benefit from the performance fix for Python 3.11+ exception handling.
affects: <6.1.7 (when analyzing Python 3.11+ bytecode)
gotchaAttempting to disassemble bytecode and then reassemble it using `xasm` (a related project) and execute the result can lead to `TypeError` or other runtime issues, particularly with functions that have the same name or complex closures. `xdis` focuses on disassembly and analysis, and perfect round-tripping for execution via reassembly is not guaranteed or fully supported across all cases.
fix
If bytecode manipulation for execution is required, proceed with caution and thorough testing. Recognize that `xdis` is primarily an analysis tool. Direct re-execution of `xasm`-generated bytecode might require deeper understanding of Python's internal code object structure beyond what basic disassembly/assembly provides. Consider `uncompyle6` for dekompilation to source if re-execution is the goal.
affects: All versions (when attempting `disasm` -> `xasm` -> execute)
Errors
Common errors & fixes
KeyError: 'X.Y.Z' (e.g., 'KeyError: '3.7.5'') when importing xdis or a library using it (like uncompyle6).
This error often indicates that `xdis` is trying to process bytecode from a Python version for which it doesn't have the necessary opcode or magic number definitions, or there's a mismatch between the bytecode version and the `xdis` version's capabilities. This can be exacerbated by incorrect installation for older Python versions.
fix
Ensure `xdis` is up-to-date (current version is 6.3.0). If you are processing bytecode from an older or very new Python version, verify that your installed `xdis` version explicitly supports that target Python version. For installations on Python < 3.11, ensure you followed the specific installation instructions for pre-built wheels/tarballs. If using `uncompyle6`, ensure both `uncompyle6` and `xdis` are the latest compatible versions.
TypeError: unsupported operand type(s) for +: 'function' and 'function' (or similar runtime errors) after disassembling bytecode with `pydisasm --asm` and reassembling with `pyc-xasm`.
This error typically occurs when bytecode is reassembled (e.g., using `xasm`) and then executed. The reassembly process, particularly when dealing with complex code objects, multiple functions, or specific optimizations, may not perfectly replicate the original bytecode structure required for Python's interpreter, leading to runtime type mismatches or incorrect references.
fix
The primary purpose of `xdis` is analysis, not necessarily perfect round-trip bytecode editing and re-execution. If you encounter this, understand that direct bytecode manipulation for execution can be very fragile. Verify the `xasm` project's documentation and current status for any known limitations or specific usage patterns to ensure executable output. Consider higher-level tools like `uncompyle6` for dekompilation if source code re-generation is the goal for execution.
Incorrect or unexpected disassembly output, especially for `MAKE_FUNCTION` or exception handling blocks when analyzing Python 3.11+ bytecode.
Older versions of `xdis` (pre-6.1.7) had less robust handling for changes in Python 3.11's bytecode, specifically regarding `MAKE_FUNCTION` formatting and an O(n^2) performance issue in exception handling. This could lead to misinterpretation or incomplete display of the bytecode structure.
fix
Upgrade `xdis` to version 6.1.7 or newer to get the latest fixes and improvements for Python 3.11+ bytecode analysis. This ensures that the disassembly accurately reflects the behavior of newer Python interpreters.
Upgrade
Version history
6.3.0latest on PyPI · released Mar 30, 2026
Audit
Dependencies
sixrequiredPython 2/3 compatibility layer, used internally by xdis.
clickrequiredCommand-line interface toolkit, used for the pydisasm utility.
Agent activity
49 hits · last 30 days
node
46
OpenAI (training)
1
Resources
xdis — pip install xdis · libregistry