pyobfus — the Python obfuscator

pyobfus (pronounced as "Python obfuscator") is a modern, AST-based python-obfuscator / code-obfuscator for developers who need to obfuscate before shipping while keeping failures diagnosable. Framework-aware presets, reverse stack-trace mapping, and a machine-readable JSON CLI let Claude Code, Cursor, GitHub Copilot, Codex, CodeBuddy, and any MCP-compatible AI agent help debug obfuscated stack traces. A transparent, open-source alternative to PyArmor.

A Python code obfuscator built with AST-based transformations. Supports Python 3.9 through 3.14. Provides reliable name mangling, string encoding, control-flow flattening, AES-256 string encryption, and — unique to pyobfus — a reverse-mapping workflow that lets you (or your AI coding assistant) debug obfuscated stack traces without giving up the protection.

🔒 Pro Edition available — 6 patent-targeted protection mechanisms (Selective Opacity, forensic watermarking, Runtime String Vault, and more) layered on top of the free AST obfuscator, $45 one-time, no subscription. See Pro Edition below.

🔎 What's new in v0.5.23 — generated files no longer embed the absolute path of the input file, which previously disclosed the build machine's directory layout in every shipped file. Output now carries a versioned # pyobfus:generated attribution marker naming the tool version and a project-relative source path; --no-community-marker (or community_marker: "off") suppresses it where generated banners are forbidden. Transformation behavior is unchanged.

🔔 Starring this repo doesn't notify you about new releases — GitHub only sends release notifications to people who explicitly Watch it. Click Watch → Custom → Releases (top of this page) to get a heads-up the moment a new version ships, without the noise of every commit/issue.

🔌 Companion MCP server: pyobfus-mcp

This repository ships two installable packages:

Package	What it is	Install
pyobfus	The Python obfuscator (CLI + library).	pip install pyobfus
pyobfus-mcp	A Model Context Protocol (MCP) server that exposes pyobfus's tools to AI coding agents.	uvx pyobfus-mcp (zero-install) or pip install pyobfus-mcp

The MCP server lives in pyobfus_mcp/ and is built on the official Model Context Protocol Python SDK (FastMCP). It registers eight MCP tools so Claude Desktop, Claude Code, Cursor, Windsurf, Zed, and Codex can call pyobfus directly from agent conversations — no shelling out:

MCP tool	Implementation	Purpose
protect_project	pyobfus_mcp/tools.py	One-call, self-verifying pipeline: scan → preset → obfuscate → byte-compile + import-smoke-test the output → return verified: true/false. The agent reports a green check instead of hoping the transform didn't break anything
check_obfuscation_risks	pyobfus_mcp/tools.py	Pre-flight risk scan; pass verify_dependencies_online=true to check declared package names against public PyPI.
generate_pyobfus_config	pyobfus_mcp/tools.py	Auto-detect framework → write a working pyobfus.yaml
unmap_stack_trace	pyobfus_mcp/tools.py	Reverse obfuscated identifiers in a production stack trace
list_presets	pyobfus_mcp/tools.py	Enumerate community / framework / Pro presets
explain_preset	pyobfus_mcp/tools.py	Describe what a named preset changes
recommend_tier	pyobfus_mcp/tools.py	Analyze a project and recommend community vs Pro tier, with reasoning
start_pro_trial	pyobfus_mcp/tools.py	Return structured guidance for starting the 5-day Pro trial

The server is registered in the official MCP Registry under io.github.zhurong2020/pyobfus-mcp. The transport is stdio. See pyobfus_mcp/README.md for per-client configuration snippets.

🧩 Claude Code skill / plugin

This repo is also a Claude Code plugin marketplace. The pyobfus-protect skill teaches an agent the full "protect Python before shipping — obfuscate and verify it still runs" workflow (MCP-first, CLI fallback):

/plugin marketplace add zhurong2020/pyobfus
/plugin install pyobfus@pyobfus

See skills/ for the skill and install details. (This is distinct from templates/ai-integration/, which are copy-in rule files for your project.)

🧑‍💻 VS Code extension

pyobfus is also on the VS Code Marketplace and Open VSX (publisher zhurong2020, same version on both — Open VSX covers VSCodium, Gitpod, Eclipse Theia and code-server) — the first obfuscation-focused extension in this category, since no competitor (PyArmor, Nuitka, Sourcedefender) has one. Inline obfuscation-risk diagnostics (pyobfus --check findings rendered via VS Code's native DiagnosticCollection API — squiggles + Problems panel, no separate linter to configure), a "Reverse Stack Trace" command, a status bar item showing your current tier with a one-click menu (Check Workspace / Generate Config / Start Trial / Unlock Pro), a "Generate pyobfus.yaml" command, and right-click "Obfuscate with pyobfus" from the Explorer or editor. Source and design rationale in vscode-extension/ and docs/VSCODE_EXTENSION_PLAN.md.

🤖 AI-native features

• pyobfus --check src/ — config-aware pre-flight risk scan: detects eval/exec, dynamic attribute access, framework reflection points, and declared dependencies that do not exist on public PyPI before you obfuscate. It honors the same explicit/discovered config and presets as a build; findings from excluded files are reported separately without affecting the primary result. Use --no-config for the legacy unfiltered scan and --offline to skip PyPI lookups. JSON includes effective_config, excluded_findings, and an ai_hint telling your AI assistant what to run next. Add --sarif pyobfus.sarif to also emit a SARIF 2.1.0 report for GitHub Code Scanning (see docs/SARIF_CODE_SCANNING.md).
• uses: zhurong2020/pyobfus-action@v1 — run the pre-flight scan or an obfuscated build in GitHub Actions, with SARIF wired to Code Scanning and a findings table in the job summary. It separates findings from tool errors, so fail-on: never lets a SARIF upload run first without the || true workaround swallowing a mistyped path. Repo: zhurong2020/pyobfus-action · Marketplace.
• pyobfus --init src/ — zero-config onboarding: scans the project, detects FastAPI/Django/Pydantic/Click/SQLAlchemy, and writes a ready-to-use pyobfus.yaml.
• pyobfus --unmap --trace error.log --mapping mapping.json — reverse obfuscated identifiers in a production stack trace so you can debug (or hand the trace to an AI assistant) without reversing the obfuscation itself.
• pyobfus … --save-mapping mapping.json --trace-marker — stamp each obfuscated file with a # pyobfus:obfuscated header (id + mapping filename + the exact --unmap command) so an AI agent that lands in an obfuscated file from a traceback immediately knows it's pyobfus output and how to reverse the names.
• pyobfus … --no-community-marker — generated files normally open with a versioned # pyobfus:generated marker naming the tool version, edition, and the project-relative source path, so anyone (or any agent) opening the file knows it is generated output rather than something to edit. It never contains an absolute path, buyer id, licence key or hash. It is transparent attribution — a plain comment you can delete — not a licence check or an anti-piracy measure, and suppressing it is a free-tier feature, not a paid one. Distinct from --trace-marker, which is about reversing tracebacks.
• pyobfus … --provenance-manifest provenance.json — write a local JSON manifest (input/output hashes, config hash, pyobfus version, git commit when available, mapping digest, CycloneDX-compatible component relationships, and a self-consistency integrity digest — not a cryptographic signature) for offline build provenance. See docs/PROVENANCE_MANIFEST.md.
• pyobfus --verify-provenance-manifest provenance.json --json — validate the manifest structure, CycloneDX-compatible relationships, and local integrity digest before archiving or shipping it.
• pyobfus … --dry-run --json — preview a versioned plan object before anything is written: the effective configuration, which files are selected or excluded (and why), and the artifacts a build would produce, each tagged ship / retain-internal / optional. Relative labels only (no source, secrets, or absolute paths); it is a preview, not a saved apply file.
• pyobfus … --verify-syntax — opt-in post-build check: compiles every generated .py in memory (no import, no execution, no __pycache__) and reports syntax_valid in JSON. A failure blocks delivery; it makes no runtime-correctness claim.
• Release provenance — pyobfus and pyobfus-mcp are published through PyPI Trusted Publishing with PEP 740 attestations; see docs/RELEASE_PROVENANCE_VERIFICATION.md for verification commands and the current snapshot.
• Framework-aware presets — --preset fastapi | django | flask | pydantic | click | sqlalchemy | ml with built-in exclusions for dispatch methods, decorators, ORM fields, migrations, model-serving wrappers, and dependency-injection parameters.
• Compatibility cookbooks — pair pyobfus with real delivery pipelines: import-hook / encrypted-file (SOURCEdefender .pye), compiled packaging (Nuitka / Cython), and ML model-serving. pyobfus --check also emits compatibility_advisory findings for these. See docs/IMPORT_HOOK_COOKBOOK.md, docs/COMPILED_PACKAGING_COOKBOOK.md, and docs/MODEL_SERVING_COOKBOOK.md. For a hardened Python 3.14+ deployment that uses anti-debug protection, --check also flags PEP 768 remote-debug exposure (which must be disabled at interpreter startup, not by the obfuscator) — see docs/REMOTE_DEBUG_HARDENING.md.
• Global --json — every CLI mode (obfuscate, --check, --unmap, --init) emits the same structured schema with an ai_hint field, ready for Claude Code, Cursor, Windsurf, and MCP servers to consume.

Features

✅ Free Edition

The following features are fully implemented and available in the current version:

• Cross-File Obfuscation: Consistent name obfuscation across multiple files

  • Automatic import statement rewriting
  • __all__ list updates with obfuscated names
  • Global symbol table with collision detection
  • Two-phase obfuscation pipeline (Scan → Transform)
  • Preview mode with --dry-run flag

• Name Mangling: Rename variables, functions, classes, and class attributes to obfuscated names (I0, I1, I2...)

• Comment Removal: Strip comments and docstrings

• String Encoding: Base64 encoding for string literals with automatic decoder injection

• Numeric / Constant Obfuscation (--numeric-obfuscation): replace integer and float literals with value-preserving opaque expressions (int → XOR/add/sub identities, float → float.fromhex) so the original constants no longer appear in the shipped source

• AI Provenance Stripping (--strip-ai-artifacts): remove AI-generation markers (e.g. Generated by Claude, Co-Authored-By: Claude) from docstrings and attribution dunders, so AI-assisted code doesn't ship with "this was AI-generated" fingerprints

• Incremental Builds (--incremental): skip a directory rebuild when every input file and the config are unchanged since the last successful build (cache at <output>/.pyobfus-cache/), useful in CI pipelines that cache artifacts

• Parameter Preservation: Preserve function parameter names for keyword argument compatibility (--preserve-param-names)

• Multi-file Support: Obfuscate entire projects with preserved import relationships

• File Filtering: Exclude files using glob patterns (test files, config files, etc.)

• Configuration Files: YAML-based configuration for repeatable builds

• Selective Obfuscation: Preserve specific names (builtins, magic methods, custom exclusions)

• Configuration Presets: --preset safe | balanced | aggressive for quick obfuscation-strength tradeoffs, plus framework-aware presets — --preset fastapi | django | flask | pydantic | click | sqlalchemy | ml — with built-in exclusions for dispatch methods, decorators, ORM fields, migrations, and dependency-injection parameters. --list-presets shows them all

• Pre-flight Risk Scanning (--check): detects eval/exec, dynamic attribute access, and framework reflection points before you obfuscate; add --sarif PATH to export findings as SARIF 2.1.0 for GitHub Code Scanning

• Reverse Stack-Trace Mapping (--unmap): reverse obfuscated identifiers in a production stack trace, so you (or an AI coding assistant) can debug without un-obfuscating the shipped code

• Build Provenance (--provenance-manifest, v0.5.5+): local JSON manifest of an obfuscation run — input/output file hashes, config hash, pyobfus version, git commit when available, mapping digest, and CycloneDX-compatible component relationships — for offline build provenance, no network calls

• Provenance Validation (--verify-provenance-manifest): validates manifest shape, CycloneDX-compatible relationships, and the local integrity digest; JSON output is available for CI/agent use

• Structured Dry-Run Plan (--dry-run --json, v0.5.19+): versioned plan object — effective config, selected/excluded files with reasons, and artifacts tagged ship / retain-internal / optional; relative labels only, preview-only (not applyable)

• Syntax-Only Output Verification (--verify-syntax, v0.5.19+): after a build, compiles generated Python in memory — no import, no execution, no __pycache__ — and reports syntax_valid in JSON; a failure blocks delivery and it makes no runtime-correctness claim

• Release Attestations: PyPI Integrity API / PEP 740 runbook for verifying pyobfus and pyobfus-mcp release artifacts

🔒 Pro Edition

The following advanced features are available with a Pro license:

• String Encryption

  • AES-256 encryption for strings
  • Runtime decryption with injected decoder
  • Automatic key generation

• Anti-Debugging

  • Debugger detection checks injected into functions
  • Four detection methods (v0.5.11): sys.gettrace() (Python-level tracers/debuggers), TracerPid via /proc/self/status (native debuggers on Linux — gdb, strace), WinAPI IsDebuggerPresent() (native debuggers on Windows), and a timing-skew check (catches single-stepping regardless of platform)
  • Default OFF to protect AI-debuggability; opt-in via --anti-debug
  • Heuristic, not a security boundary — documented in the CHANGELOG

• Control Flow Flattening

  • State machine transformation for if/else/elif
  • For/while loop flattening
  • Nested structure support
  • CLI: --control-flow

• Dead Code Injection

  • Insertion of unreachable code paths
  • Four strategies: after-return, false branches, opaque predicates, decoy functions
  • CLI: --dead-code

• License Embedding

  • Embed expiration dates: --expire 2025-12-31
  • Machine binding: --bind-machine
  • Run count limits: --max-runs 100
  • Offline verification - no external dependencies

• Runtime Policy (v0.5.9)

  • Refuse to import outside a build-time platform allowlist — a pure-Python generalization of PyArmor BCC's platform restrictions
  • OS allowlist: --requires-os Linux,Darwin
  • Minimum Python version: --requires-python-min 3.10
  • CPU architecture allowlist: --requires-arch x86_64,arm64
  • Any combination composes; each check is independent

• Embedded Encrypted Data (v0.5.10)

  • AES-256-GCM encrypt a resource file at build time and embed it base85-encoded in the output — closes the Nuitka Commercial "Protect Data Files" / PyArmor --bind-data gap
  • CLI: --embed-data path/to/resource.bin
  • Generates a get_embedded_data() accessor that decrypts on call, not at import

• Configuration Presets

  • --preset trial - 30-day time-limited version
  • --preset commercial - Maximum protection with machine binding
  • --preset library - For pip-distributable libraries
  • --preset maximum - Highest security with all protections
  • --list-presets - View all presets

Patent-targeted mechanisms (CN 202610712171X, introduced v0.5.0)

Six mechanisms, available both as the pyobfus_pro API and — as of v0.5.1 — as opt-in pyobfus build flags (single-file / --no-cross-file mode): --selective-opacity, --seal-code, --vault, --scrub-traceback, --fingerprint <buyer-id>, --expire-hard <date>. v0.5.3 adds --period <N> (run-counter limit), --opacity-config <opacity.toml> (pattern-driven L3 encryption by original qualname), and --bind-device / --bind-device-id <id> (device-locked L3 encryption). v0.5.4 extends --bind-device to Runtime String Vault keys too — previously only the Selective Opacity L3 layer was device-locked, so vault secrets decrypted on any machine; now each vault key is independently re-derived at runtime from the bound device.

• Selective Opacity — per-symbol protection layers (transparent / ai-readable / obfuscated / AES-256-GCM encrypted with lazy __code__ materialization).
• Forensic watermarking — per-buyer deterministic key derivation for piracy traceback.
• License binding combo — device / expiry / run-count binding woven into the AES-GCM decryption path (no separate patchable license check).
• @seal_code — build-time bytecode integrity hash; runtime in-memory-patch detection.
• --scrub-traceback — production traceback encryption (RSA-2048 + AES-256-GCM); reverse error IDs with the new pyobfus-unscrub CLI.
• Runtime String Vault — encrypted KV namespace for runtime secrets with lazy per-entry decryption.

Requires Python ≥ 3.9 as of v0.5.0 (3.8 dropped, EOL 2024-10).

See CURRENT_PLAN_ZH.md for the current project plan and priorities.

Try Pro Features FREE

Try all Pro features for 5 days - no registration or credit card required!

# Start your free trial
pyobfus-trial start

# Check trial status
pyobfus-trial status

# Use Pro features during trial
pyobfus input.py -o output.py --level pro

What's included in the trial:

• Control flow flattening (--control-flow)
• AES-256 string encryption (--string-encryption)
• Anti-debugging protection (--anti-debug)
• Dead code injection (--dead-code)
• License embedding (--expire, --bind-machine, --max-runs)
• Configuration presets (--preset trial/commercial/library/maximum)

After your trial, purchase a license to continue using Pro features.

The trial runs on the honor system. It stores its state in an unsigned file in your home directory, and pyobfus/trial.py is readable Apache-2.0 source — so it is a convenience control, not a security boundary, and we document it as such rather than claiming protection it cannot deliver. See SECURITY.md. Note that the Community Edition has no file or line limits and needs no trial at all — the trial gates only the Pro mechanisms.

Purchase Professional Edition

Pro Edition Features:

• 🔀 Control Flow Flattening
• 🧩 Dead Code Injection
• 🔐 AES-256 String Encryption
• 📦 Import Obfuscation - runtime importlib imports with encrypted import strings
• 🛡️ Anti-Debugging Checks
• 📅 License Embedding - Expiration, machine binding, run limits
• ⚡ Configuration Presets - One-command setup
• 🔄 Lifetime Updates
• 💻 Up to 3 devices per license
• 📧 Priority Email Support

Price: $45.00 USD (one-time payment)

Payment methods: credit/debit card, Apple Pay, and WeChat Pay (微信支付) for buyers in China, plus the other options Stripe shows for your region at checkout. Alipay (支付宝) is being enabled.

How to Purchase

Visit our purchase page: pyobfus.github.io/purchase for detailed information and secure checkout.

Quick purchase: 🚀 Buy Now - Direct checkout link (Instant delivery • 30-day money-back guarantee)

3-Step Purchase Process:

1. Complete Secure Checkout (Stripe)

   • Click the buy link above or visit the purchase page
   • Enter your email (for license delivery)
   • Complete payment securely via Stripe

2. Receive License Key

   • License key delivered to your email within minutes
   • Format: PYOB-XXXX-XXXX-XXXX-XXXX
   • Check Spam/Junk folder if not in inbox

3. Activate License

   pip install --upgrade pyobfus
   pyobfus-license register PYOB-XXXX-XXXX-XXXX-XXXX
   pyobfus-license status
   

4. Start Using Pro Features

   # Quick start with presets
   pyobfus src/ -o dist/ --preset commercial   # Maximum protection
   pyobfus src/ -o dist/ --preset trial        # 30-day trial version
   pyobfus src/ -o dist/ --preset library      # For pip distribution
   
   # Individual features
   pyobfus input.py -o output.py --string-encryption
   pyobfus input.py -o output.py --import-obfuscation
   pyobfus input.py -o output.py --anti-debug
   pyobfus input.py -o output.py --control-flow
   pyobfus input.py -o output.py --dead-code
   
   # License restrictions
   pyobfus src/ -o dist/ --expire 2025-12-31 --bind-machine --max-runs 100