Python bytecode decompiler (Python 1.0–3.14) implemented in Node.js
npm install depyoDepyo converts Python .pyc files (or archives of them) back to readable Python source. It aims for broad coverage (Python 1.0 through 3.14) and fast throughput, with fixtures for modern features (exception groups, pattern matching, walrus, f-strings, async, context managers).
.pyc preservation, and flattened output paths.run-fixtures.js and run-matrix.js compare decompiled output against expected fixtures across versions.npm i -g depyonpx depyo Node.js 20+ recommended (matches CI).
``bashDecompile a single .pyc
node depyo.js /path/to/file.pyc
Without , depyo scans supported versions (oldest → newest) and accepts the first clean output when all clean candidates agree. If outputs diverge (ambiguous), it stops and asks for --py-version. Use --debug to see scan results.$3
- --asm emit .pyasm disassembly alongside source
- --raw emit raw .pyc next to output
- --raw-spacing preserve blank lines/comment gaps
- --dump dump marshalled object tree
- --stats print throughput stats
- --skip-source-gen skip writing .py (use with --asm/--dump)
- --skip-path flatten output paths (write next to input)
- --out print source to stdout instead of files
- --marshal treat input as raw marshalled data (no .pyc header, auto-scan versions)
- --marshal-scan fast scan marshal blobs and print version candidates
- --py-version bytecode version hint (use with --marshal)
- --basedir override output root (default: alongside input)
- --file-ext change emitted extension (default py)Examples
- Disassemble only (no source): node depyo.js --skip-source-gen --asm file.pyc
- Keep raw + disassembly next to source:
- Flatten outputs (helpful for bulk zips): Testing
- Smoke per version:
bash
node scripts/run-fixtures.js --root test/bytecode_3.14 --pattern py314_with_except_star --fail-fast
node scripts/run-fixtures.js --root test/bytecode_3.6 --pattern py36_fstrings --fail-fast
`
- Matrix (all versions, optional PyPy):
bash
node scripts/run-matrix.js # full sweep
node scripts/run-matrix.js --pattern py311_exception_groups --fail-fast
`
- Marshal fixtures (headerless marshal blobs):
bash
node scripts/run-marshal-fixtures.js
`
- Regenerate marshal fixtures:
bash
node scripts/generate-marshal-fixtures.js --clean
`
- Modern fixtures are generated via (Python 3.8+ on PATH).Support matrix
- Python 1.0–3.14 opcode tables with expected fixtures.
- Modern features: match/case, walrus, f-strings, exception groups, type params.
- PyPy bytecode sets decompile; expected files are not yet part of CI.
- Legacy CI smokes (1.x/2.7/3.0–3.6) are informational (continue-on-error); modern feature checks are blocking.Known limitations
- Inline comprehensions (Python 3.12+): PEP 709 inlines list/dict/set comprehensions into parent code objects. Depyo currently reconstructs these as for-loops rather than comprehension expressions. Functions, classes, match/case, exception handling, and other constructs work correctly.Contributing / DX tips
- Use node scripts/run-fixtures.js --pattern for fast repros.
- For full coverage, node scripts/run-matrix.js --fail-fast (optionally add --pattern).
- Enable --raw-spacing to inspect potential comment/blank-line gaps.
- --stats helps when profiling throughput.Comments and docs are in English; output mirrors the target Python version syntax.
Comparison snapshot (at a glance)
| Project | Supported versions | Modern features (match, walrus, f-strings, exc groups) | Delivery | Expected fixtures | Notes |
| ------------------ | --------------------------- | ------------------------------------------------------ | ------------ | ----------------- | ----------------------------------------- |
| depyo | 1.0–3.14 (PyPy decompiles) | Yes | npm/npx, CLI | Yes (1.0–3.14) | Node.js CLI, asm/raw-spacing options |
| uncompyle6/decompyle3 | 2.x–3.12+ (lag on 3.13/3.14) | Partial (depends on branch) | pip | Partial | Python-based, slower adoption of new ops |
| pycdc (C++) | Mostly 2.x–3.x (limited new) | Partial | source build | No | Fast, but modern coverage limited |
Quick benchmark (informal)
- Machine: local Node 25, single-thread.
- Case: py314_exception_groups.pyc decompiled 50× in-process: ~5.3 ms total (≈0.1 ms per decompile).
Use node depyo.js --stats for your environment.Promotion ideas (OSS)
- Announce on HN/Reddit (Show HN / r/Python) with npm/npx one-liners.
- Add to awesome lists (awesome-python, awesome-reverse-engineering).
- Provide asciinema/GIF of npx depyo file.pyc + --asm.
- Encourage contributions via Issues/Discussions and help wanted` labels.