depyo — Python bytecode decompiler in Node.js

Depyo converts Python .pyc files (or archives of them) back to readable Python source — right from Node.js, without a Python runtime. Coverage spans Python 1.0 through 3.15 plus PyPy, with first-class support for modern features: match/case, walrus, f-strings, exception groups, async/await, type parameters, PEP 696 TypeVar defaults, and t-strings (PEP 750).

npx depyo my_script.pyc
# → writes my_script.py next to the input

What it's good for

• Reverse engineering stripped Python. You have a .pyc (maybe extracted from a PyInstaller binary, an Android APK's Kivy bundle, or an old archive) and no source. Depyo reconstructs the source — even for Python versions the original uncompyle6/decompyle3 no longer follow.
• Malware / threat analysis. Quickly triage suspicious Python payloads without setting up a matching Python interpreter. Add --asm for a bytecode listing alongside the source.
• Forensics on old codebases. Resurrect Python 2.x (even 1.x) modules when the source is long gone.
• CI-side audits. Depyo is a pure Node.js CLI — drop it in any Node pipeline to spot-check compiled .pyc against expected sources, or to extract and diff shipped bytecode.
• Learning tool. Inspect how CPython lowers a given Python feature (comprehensions, pattern matching, exception groups) across versions. --asm is handy here.
• Batch processing. Feed a .zip of .pyc files and get back a mirrored tree of .py sources.

Why depyo (vs alternatives)

| Tool | Versions | Modern features¹ | Runtime | Throughput | Notes | | --------------------- | --------------------- | ---------------- | ------- | ---------- | -------------------------------------------- | | depyo | 1.0–3.15 + PyPy | Yes | Node.js | ~0.1 ms/file² | Modern opcodes land fast; no Python needed | | uncompyle6/decompyle3 | 2.x–3.12 (stalled) | Partial | Python | slower | Development largely halted on 3.13+ | | pycdc (C++) | 2.x–3.x (limited new) | Partial | native | fast | Rich history, but slow to adopt new opcodes |

¹ match/case, walrus, f-strings, exception groups, async/await, type params. ² Informal: py314_exception_groups.pyc × 50 in-process, Node 25, single thread (--stats on your machine for real numbers).

Install

npm i -g depyo          # global CLI
npx depyo <file.pyc>    # one-off, no install

Node.js 20+ recommended (CI gate).

Quick start

# Single .pyc → writes <name>.py next to it
node depyo.js /path/to/file.pyc

# ZIP of .pyc files → mirrors structure
node depyo.js my_archive.zip

# Also emit disassembly and preserve the raw .pyc
node depyo.js --asm --raw my_archive.zip

# Stream to stdout (no files written)
node depyo.js --out /path/to/file.pyc

# Flatten outputs (drop mirrored directories)
node depyo.js --skip-path /path/to/file.pyc

# Headerless marshal blob (no .pyc magic)
node depyo.js --marshal --py-version 3.11 /path/to/blob.bin
node depyo.js --marshal /path/to/blob.bin            # auto-scan
node depyo.js --marshal-scan /path/to/blob.bin       # fast scan, no decompile

Without --py-version, 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.

Example

Input greet.py:

async def greet(names: list[str], *, greeting: str = "Hello") -> None:
    seen = set()
    for name in names:
        if name in seen:
            continue
        seen.add(name)
        print(f"{greeting}, {name}!")

Compile (python3.13 -c 'import py_compile; py_compile.compile("greet.py", "greet.pyc")') then:

$ npx depyo --out greet.pyc
async def greet(names: list[str], *, greeting: str = "Hello") -> None:
    seen = set()
    for name in names:
        if name in seen:
            continue
        seen.add(name)
        print(f"{greeting}, {name}!")

Pattern matching round-trips too:

match command.split():
    case [action]:
        run(action)
    case [action, obj] if action in VERBS:
        run(action, obj)
    case _:
        print("usage: ...")

CLI options

| Option | Effect | | ------------------------ | --------------------------------------------------------------- | | --asm | Emit .pyasm disassembly alongside source | | --raw | Copy raw .pyc next to output | | --raw-spacing | Preserve blank-line / comment gaps | | --dump | Dump the marshalled object tree | | --stats | Print throughput stats | | --skip-source-gen | Skip writing .py (useful 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) | | --marshal-scan | Fast scan marshal blobs; print candidate versions | | --py-version <x.y> | Bytecode version hint (required for some headerless marshals) | | --basedir <dir> | Override output root (default: alongside input) | | --file-ext <ext> | Change emitted extension (default py) |

Programmatic API

const {PycReader} = require('depyo/lib/PycReader');
const {PycDecompiler} = require('depyo/lib/PycDecompiler');

const fs = require('fs');
const buffer = fs.readFileSync('greet.pyc');
const reader = new PycReader(buffer);
const obj = reader.ReadObject();

const decompiler = new PycDecompiler(obj);
const ast = decompiler.decompile();
console.log(ast.codeFragment().toString());

Support matrix

• Python 1.0–3.15 opcode tables and expected fixtures.
• Modern features: match/case (guards, OR-patterns, bindings, wildcards), walrus, f-strings (nested, equals-sign debug), exception groups (except*), async comprehensions, type parameters, PEP 696 TypeVar defaults, PEP 750 t-strings.
• PyPy bytecode decompiles; expected fixtures not yet part of CI.
• CI gates: Modern feature checks are blocking; legacy 1.x / 2.7 / 3.0–3.6 smokes gate as well.

Known limitations

• Inline comprehensions (3.12+): PEP 709 inlines list/dict/set comprehensions into the parent code object. Depyo currently reconstructs these as for-loops rather than comprehension expressions. Functions, classes, match/case, exception handling, and other constructs work correctly.
• Comments / blank lines: Lost in compilation and not recoverable. --raw-spacing can hint at original gaps using line-number attributes.
• Source-level AST drift: Some constructs are normalized by CPython before bytecode (e.g. if not x: raise AssertionError ↔ assert x). Depyo renders what the compiler produced.

Testing

# Smoke per version
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

# Full matrix
node scripts/run-matrix.js
node scripts/run-matrix.js --pattern py311_exception_groups --fail-fast

# Marshal-blob fixtures (headerless)
node scripts/run-marshal-fixtures.js

# Regenerate snapshot fixtures (destructive)
node scripts/generate-marshal-fixtures.js --clean

# Tier-1 oracle: parseability of every decompiled fixture
node scripts/check-parseable.js

# Tier-2 oracle: AST equivalence between source .py and decompiled .py
node scripts/check-ast-equivalence.js

# Sentinel leak gate (CI-critical)
node scripts/check-no-sentinels.js

Modern fixtures are generated via test/generate_modern_tests.py (Python 3.8+ on PATH).

Contributing

• Use node scripts/run-fixtures.js --pattern <piece> for fast repros.
• For full coverage, node scripts/run-matrix.js --fail-fast (optionally add --pattern).
• --raw-spacing helps inspect potential comment/blank-line gaps.
• --stats helps when profiling throughput.

Issues, repro .pyc files, and PRs welcome at https://github.com/skuznetsov/depyo.js/issues.

Comments and docs are in English; output mirrors the target Python version syntax.

License

MIT — see LICENSE.