{"id":14929869,"url":"https://github.com/thuml/depyf","last_synced_at":"2025-09-24T05:32:33.180Z","repository":{"id":191100559,"uuid":"683917057","full_name":"thuml/depyf","owner":"thuml","description":"depyf is a tool to help you understand and adapt to PyTorch compiler torch.compile.","archived":false,"fork":false,"pushed_at":"2025-04-20T08:09:16.000Z","size":12648,"stargazers_count":733,"open_issues_count":2,"forks_count":27,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-09-23T07:34:28.782Z","etag":null,"topics":["compiler","deep-learning","pytorch"],"latest_commit_sha":null,"homepage":"https://depyf.readthedocs.io","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/thuml.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-08-28T04:05:54.000Z","updated_at":"2025-09-22T18:06:47.000Z","dependencies_parsed_at":"2023-10-22T07:21:08.668Z","dependency_job_id":"1cb4e137-dd52-4194-938e-513489ae3b8d","html_url":"https://github.com/thuml/depyf","commit_stats":null,"previous_names":["youkaichao/depyf","thuml/depyf"],"tags_count":20,"template":false,"template_full_name":null,"purl":"pkg:github/thuml/depyf","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thuml%2Fdepyf","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thuml%2Fdepyf/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thuml%2Fdepyf/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thuml%2Fdepyf/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thuml","download_url":"https://codeload.github.com/thuml/depyf/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thuml%2Fdepyf/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":276573572,"owners_count":25666244,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-23T02:00:09.130Z","response_time":73,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["compiler","deep-learning","pytorch"],"created_at":"2024-09-23T15:01:23.974Z","updated_at":"2025-09-24T05:32:33.171Z","avatar_url":"https://github.com/thuml.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"![Logo](imgs/logo-and-text.svg)\n\n[![Documentation Status](https://readthedocs.org/projects/depyf/badge/?version=latest)](https://depyf.readthedocs.io/en/latest/) ![Supported Python Versions](https://img.shields.io/badge/python-%203.7%20%7C%203.8%20%7C%203.9%20%7C%203.10%20%7C%203.11-blue) ![Python Decompilation Tests](https://github.com/thuml/depyf/actions/workflows/test_decompile.yml/badge.svg) ![PyTorch Integration Tests](https://github.com/thuml/depyf/actions/workflows/test_pytorch.yml/badge.svg) [![Test Coverage](https://codecov.io/github/thuml/depyf/graph/badge.svg?token=DUQ1CQ0I5U)](https://codecov.io/github/thuml/depyf) ![MIT License](https://img.shields.io/github/license/thuml/depyf)\n\n\u003e `depyf` is proud to be a [PyTorch ecosystem project](https://pytorch.org/ecosystem/). Check out the announcement blog [https://pytorch.org/blog/introducing-depyf/](https://pytorch.org/blog/introducing-depyf/) for more details.\n\nHave you ever felt overwhelmed by the complexities of `torch.compile`? Diving into its workings can feel like black magic, with bytecode and Python internal details that many users fail to understand, hindering them from understanding and adapting to `torch.compile`.\n\nIf you also face the problem, then you might be interested in `depyf`. As the logo suggests, `depyf` is a software tool to leverage advanced Python features (the Python snake symbol) to open up internal details (the internal gears symbol) of PyTorch's compiler `torch.compile` (the PyTorch logo), so that users can understand it, adapt to it, and tune their code (the debugger symbol) to get maximum performance benefit out of it.\n\n:warning: This project is developed under close collaborations with the PyTorch team. Therefore, it requires very new features from PyTorch to support better understanding of `torch.compile`. **Please use this project along with PyTorch\u003e=2.2.0 (PyTorch nightly is recommended)**. Visit the [PyTorch website](https://pytorch.org/) for how to install different versions of PyTorch.\n\n:warning: During development, we seek suggestions from the community quite a lot. You may find some early usage examples from some discussion forums or social media platforms. **Please follow the latest documentation for how to use this tool.**\n\n# Why `depyf`?\n\nIf you want to understand bytecode generated by `torch.compile`, then `depyf` might be the only choice for you. Below we tested several existing decompilers, they struggle to decompile simple Python bytecode across versions, and have poor support for PyTorch.\n\n| Decompiler  | Python 3.8   | Python 3.9 | Python 3.10 | Python 3.11 | PyTorch |\n|-------------|--------------|------------|-------------|-------------|---------|\n| [decompyle3](https://github.com/rocky/python-decompile3)  | 90.6% (77/85)  | ×          | ×           | ×           | ×       |\n| [uncompyle6](https://github.com/rocky/python-uncompyle6)  | 91.8% (78/85)| ×          | ×           | ×           | ×       |\n| [pycdc](https://github.com/zrax/pycdc)       | 74.1% (63/85)  | 74.1% (63/85)| 74.1% (63/85) | 67.1% (57/85)          | 19.3% (27/140)|\n| [depyf](https://github.com/thuml/depyf)       | 100% (85/85) | 100% (85/85)| 100% (85/85)| 100% (85/85)| 100% (140/140)|\n\n# Installation\n\nStable release: `pip install depyf`\n\nNightly version (recommended): `pip install git+https://github.com/thuml/depyf.git`\n\n# Usage\n\nThe main usage is quite simple: just wrap your code within a context manager:\n\n```python\nimport torch\nfrom torch import _dynamo as torchdynamo\nfrom typing import List\n\n@torch.compile\ndef toy_example(a, b):\n    x = a / (torch.abs(a) + 1)\n    if b.sum() \u003c 0:\n        b = b * -1\n    return x * b\n\ndef main():\n    for _ in range(100):\n        toy_example(torch.randn(10), torch.randn(10))\n\nif __name__ == \"__main__\":\n    # main()\n    # surround the code you want to run inside `with depyf.prepare_debug`\n    import depyf\n    with depyf.prepare_debug(\"./dump_src_dir\"):\n        main()\n```\n\nThen you can see all the details of `torch.compile` inside the directory `./dump_src_dir`. The details are organized into the following:\n\n- `full_code_for_xxx.py` for each function using `torch.compile`\n- `__transformed_code_for_xxx.py` for Python code associated with each graph.\n- `__transformed_code_for_xxx.py.xxx_bytecode` for Python bytecode, dumped code object, can be loaded via `dill.load(open(\"/path/to/file\", \"wb\"))`. Note that the `load` function might import some modules like `transformers`. Make sure you have these modules installed.\n- `__compiled_fn_xxx.py` for each computation graph and its optimization:\n  - `Captured Graph`: a plain forward computation graph\n  - `Joint Graph`: joint forward-backward graph from `AOTAutograd`\n  - `Forward Graph`: forward graph from `AOTAutograd`\n  - `Backward Graph`: backward graph from `AOTAutograd`\n  - `kernel xxx`: compiled CPU/GPU kernel wrapper from Inductor.\n\nWe collect [all the compilation artifacts](https://github.com/thuml/learn_torch.compile) when testing over 100 deep learning models. You can take a look to learn how the PyTorch compiler works.\n\nIf you want to use debugger to step through the above code, just add another context manager (and launch the script through debuggers):\n\n```python\nimport torch\nfrom torch import _dynamo as torchdynamo\nfrom typing import List\n\n@torch.compile\ndef toy_example(a, b):\n    x = a / (torch.abs(a) + 1)\n    if b.sum() \u003c 0:\n        b = b * -1\n    return x * b\n\ndef main():\n    for _ in range(100):\n        toy_example(torch.randn(10), torch.randn(10))\n\nif __name__ == \"__main__\":\n    import depyf\n    with depyf.prepare_debug(\"./dump_src_dir\"):\n        main()\n    # surround the code you want to debug inside `with depyf.debug()`\n    with depyf.debug():\n        main()\n```\n\nCalling `depyf.debug()` will pause the program for you to set breakpoints, and then you can use debuggers to hit breakpoints in these files under the `./dump_src_dir` directory you specified above.\n\n# Contact\n\nIf you have any question about `depyf`, feel free to open issues to reach out! Any discussion/issue report/PR is welcome. Or contact youkaichao@gmail.com if you have any other questions.\n\n# Citing `depyf`\n\nIf you find `depyf` useful, please cite it in your publications.\n\n```latex\n@article{you2024depyf,\n      title={depyf: Open the Opaque Box of PyTorch Compiler for Machine Learning Researchers}, \n      author={Kaichao You and Runsheng Bai and Meng Cao and Jianmin Wang and Ion Stoica and Mingsheng Long},\n      year={2024},\n      eprint={2403.13839},\n      journal={arXiv},\n      primaryClass={cs.LG},\n      url={https://github.com/thuml/depyf}\n}\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthuml%2Fdepyf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthuml%2Fdepyf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthuml%2Fdepyf/lists"}