Install & Compatibility
Where this runs
tested against v0.20.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
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
decompile
✓ from depyf import decompile
prepare_debug
✓ import depyf
with depyf.prepare_debug(...)
debug
✓ import depyf
with depyf.debug()
This example demonstrates how to use `depyf` to inspect the code generated by `torch.compile`. Wrapping the `main` function (which calls the `torch.compile`d `toy_example`) with `depyf.prepare_debug` will decompile and dump the generated source code into the specified directory (`./debug_dir`). You can then examine these files to understand PyTorch's compiler optimizations. The `depyf.debug()` context manager can be used to pause execution for interactive debugging with breakpoints.
import torch
import depyf
@torch.compile
def toy_example(a, b):
x = a / (torch.abs(a) + 1)
if b.sum() < 0:
b = b * -1
return x * b
def main():
for _ in range(100):
toy_example(torch.randn(10), torch.randn(10))
# Wrap the code that triggers compilation within depyf.prepare_debug
# This will dump decompiled source code to './debug_dir'
with depyf.prepare_debug("./debug_dir"):
main()
# Optional: Use depyf.debug() to pause execution and set breakpoints
# The program will pause here, allowing you to browse files in ./debug_dir
# and set breakpoints before continuing execution.
# with depyf.debug():
# output = toy_example(torch.randn(10), torch.randn(10))
print("Decompiled code and debug info available in ./debug_dir")
depyf --version
Debug
Known issues
breakingdepyf requires a recent version of PyTorch, specifically `>=2.2.0`, and often recommends using PyTorch nightly builds due to its close integration with the rapidly evolving `torch.compile` stack. Older PyTorch versions may lead to compatibility issues or incorrect decompilation.fixUpgrade PyTorch to version 2.2.0 or newer, preferably using a nightly build if encountering issues.
affects: <2.2.0 of PyTorch
gotchadepyf is a specialized decompiler focused on bytecode generated by `torch.compile`. It is not a general-purpose Python bytecode decompiler and may not fully support all Python syntax (e.g., `async/await`, complex `while` loops, or intricate `if/else` patterns outside of PyTorch's optimized graphs).fixUnderstand that depyf's scope is primarily for PyTorch-generated bytecode. For general Python decompilation, other tools might be necessary, though they often struggle with PyTorch bytecode.
affects: All
gotchaThe output source code generated by depyf is semantically equivalent to the original bytecode but may not be syntactically identical. It often includes verbose details (e.g., explicit `return None`) that are typically implicit in human-written Python code.fixBe aware that the decompiled output serves as a detailed representation of the bytecode's operations, not a precise reconstruction of the original Python source. Focus on the logical flow rather than exact syntax.
affects: All
deprecatedThe `TORCH_COMPILE_DEBUG` environment variable, while providing debug information for `torch.compile`, produces logs that are generally much harder to parse and understand compared to `depyf`'s human-readable decompiled source. Relying solely on `TORCH_COMPILE_DEBUG` is inefficient for deep analysis.fixPrioritize using `depyf`'s context managers (`prepare_debug`, `debug`) for a clearer and more organized understanding of `torch.compile`'s internal workings.
affects: PyTorch 2.x
gotchaThe `DEPYF_REMOVE_TEMP` environment variable, introduced in v0.20.0, can affect whether temporary files generated during decompilation are removed. If you need to inspect intermediate artifacts, ensure this is not set or set appropriately.fixSet `DEPYF_REMOVE_TEMP=0` in your environment if you wish to retain temporary files generated by depyf for further inspection.
affects: >=0.20.0
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'depyf'
The depyf library is not installed in the current Python environment.
fixRun `pip install depyf` to install the library.
ImportError: cannot import name 'prepare_debug' from 'depyf'
Users are attempting to import `prepare_debug` directly from the `depyf` package, but it is intended to be accessed as an attribute of the `depyf` module.
fixImport the `depyf` module and then use `depyf.prepare_debug` (e.g., `import depyf; with depyf.prepare_debug('debug_dir'):`). TypeError: Decompiler.generic_jump_if incorrect end_index selection causes TypeError with torch.compile bytecode
This error indicates an internal issue within depyf's decompiler when processing certain complex or unsupported bytecode generated by `torch.compile`, often related to specific control flow patterns.
fixThis is a library bug that often requires a fix in depyf itself. Check the depyf GitHub issues for updates, or try updating `depyf` and PyTorch to their latest nightly versions, as depyf works closely with PyTorch releases and bug fixes are frequent.
AttributeError: 'NoneType' object has no attribute 'dict_getitem'
This error occurs when depyf's integration with other libraries (like vLLM) or specific `torch.compile` debug configurations leads to an attempt to access attributes on a `None` object, suggesting an unexpected state during bytecode processing or graph capture.
fixEnsure compatible versions of depyf and PyTorch, and any integrating libraries, are used. Review the specific code context where `depyf` is used, particularly around `torch.compile` parameters, for any patterns that might lead to `None` values where objects are expected. Updating depyf to its latest version might also contain a fix.
AttributeError: 'Embedding' object has no attribute 'in_features'
This error typically arises when `depyf` or `torch.compile` attempts to decompile or process a PyTorch model's `Embedding` layer in a way that expects a non-existent attribute like `in_features`, possibly due to version mismatches or assumptions about the model's structure.
fixVerify that your PyTorch and depyf versions are compatible and up-to-date (PyTorch >= 2.2.0 is recommended for depyf). If the issue persists, this may indicate a deeper compatibility problem with how `torch.compile` or `depyf` handles specific model architectures, and reporting it to the depyf GitHub issues with a minimal reproducible example would be beneficial.
Upgrade
Version history
0.20.0latest on PyPI · released Oct 13, 2025
Audit
Dependencies
torchrequireddepyf is designed to work with PyTorch's `torch.compile` and requires PyTorch>=2.2.0 (PyTorch nightly is often recommended for best compatibility).