pyobfus: the Python obfuscator

pyobfus Logo

Obfuscate Python before you ship it—and still debug what you shipped.

pyobfus is a local-first, AST-based Python obfuscator for Python 3.9–3.14. It handles complete projects, keeps generated output portable, and can reverse-map protected production tracebacks for developers and AI coding agents. Community is Apache-2.0, has no file or line limits, and requires no trial.

What's new in v0.5.32: fixes directory builds that raised NameError on import when a module used its own decorator, base class, metaclass, or a lambda referring to a module name (0.5.10 to 0.5.31). If you shipped a directory build, rebuild and rerun your tests. v0.5.31 also removed docstrings from directory builds and added --unmap mapping checks; see the changelog.

Why pyobfus

Advantage	What it means in practice
Complete Community edition	Obfuscate real projects without a file/line cap or trial clock. Optional limits are your CI safety rails, not an upgrade gate.
Diagnosable protection	Keep the private mapping and restore identifiers in production tracebacks without giving customers the original source.
Evidence, not a black box	Scan, preview, verify syntax, retain provenance and compare reproducible build reports.
Portable and local-first	Source stays local; Community emits ordinary cross-platform Python without a native build matrix.
Explicit security claims	Tested, verified-once and advisory-only claims are separated; deterrents are not presented as irreversible security.

Quick start

pip install pyobfus

# Check compatibility, preview, then build
pyobfus --check src/
pyobfus src/ -o dist/ --dry-run --json
pyobfus src/ -o dist/ --save-mapping mapping.json --verify-syntax
# --verify-syntax only compiles the output; run your own tests against dist/

# Restore names when a production traceback arrives
pyobfus --unmap --trace error.log --mapping mapping.json

For framework presets, configuration discovery, packaging and verification, start at the task-oriented documentation.

Minimal example

Input:

def greet(name):
    message = f"Hello, {name}!"
    return message

print(greet("world"))

Run pyobfus input.py -o output.py. Representative Community output:

def I0(I1):
    I2 = f"Hello, {I1}!"
    return I2

print(I0("world"))

Both print Hello, world!. Generated identifiers can differ with input and configuration; verify the exact output with your own tests. Keep a mapping when you need to restore names from a shipped traceback.

Features at a glance

Community includes name mangling with import rewriting across a project (for directories: module-level names; single files also rename methods, locals and parameters, see the guide), string and numeric transforms, framework-aware presets, config-aware pre-flight scanning, SARIF, structured dry-run, reverse traceback mapping, syntax verification, provenance, reproducible output and verifiable build reports.

Professional adds four kinds of commercial value:

Protection strength: AES encryption, control-flow flattening, dead-code injection, anti-debugging, Selective Opacity and sealing.
Protected assets: import strings, embedded data, Runtime String Vault and protected tracebacks.
Distribution control: device, expiry, run-count, platform and application-supplied-key policies.
Accountability: forensic watermarking and buyer-specific builds.

The durable classification rule is documented in the Community / Pro boundary policy.

🔌 Companion MCP server: `pyobfus-mcp`

Install the MCP server with no API key and no source upload:

uvx pyobfus-mcp
# or: pip install pyobfus-mcp

It exposes structured tools for scanning, configuration, protection, verification, preset explanation, tier recommendations and traceback mapping. See the MCP package guide and its registration in the official MCP Registry.

Agent and editor integrations

pyobfus-review and pyobfus-protect skills separate read-only review from build-producing work. See skills.
The VS Code extension provides inline risk diagnostics and traceback reversal; it is also on Open VSX.
zhurong2020/pyobfus-action@v1 runs scans or verified builds in GitHub Actions with SARIF support.
The stable JSON CLI includes reason codes and an ai_hint next action.
Agent-readable project facts are published in llms.txt, while contributor instructions live in AGENTS.md.

All Agent guidance is public and human-auditable. pyobfus does not serve hidden instructions or different facts based on User-Agent.

Configuration

Generate a starting configuration or use a named preset:

pyobfus --init src/
pyobfus src/ -o dist/ --preset django
pyobfus --list-presets

Community presets include safe, balanced, aggressive, fastapi, django, flask, pydantic, click, sqlalchemy and ml. See the documentation home and pyobfus --help for current options. Optional max_files and max_total_loc values are user-selected safety limits at every tier.

How do I debug an obfuscated crash with an AI assistant?

Build with --save-mapping mapping.json, keep that file private, then run:

pyobfus --unmap --trace error.log --mapping mapping.json

The restored identifiers can be read by you or an AI assistant without giving the customer your mapping or original source. --trace-marker can also stamp generated files with the exact recovery command.

Purchase Professional Edition

Professional Edition is $45 USD, one time—not a subscription. A five-day trial requires no registration or card:

pyobfus-trial start

The trial is an honor-system convenience control, not a security boundary. Visit the product and purchase page for current payment methods, refund terms and purchase steps. After purchase, use the license activation guide.

Runtime-backed Pro artifacts depend on the separately redistributable, pure-Python pyobfus-runtime package. Target machines do not need the complete proprietary builder or a licence key.

Security and limitations

Obfuscation raises the cost of inspection; it does not make client-side Python irreversible. Runtime-decrypted material can be observed by a determined attacker. Keep credentials and authorization decisions behind environment, secret-manager or server boundaries.

Comparison and deployment guides

Architecture and development

The product line separates the Apache-2.0 Core, proprietary Pro builder, redistributable runtime, MCP package, editor extension and GitHub Action. See:

Community and citation

Use GitHub Issues for bugs and Discussions for questions and ideas. Citation metadata is in CITATION.cff, with archival DOI 10.5281/zenodo.20846053.

Core is Apache-2.0; Professional implementation is proprietary. See LICENSE-NOTICE.md.

obfuscation code-protection security python ast code-obfuscator python-obfuscator name-mangling string-encryption anti-debug control-flow-flattening pyarmor-alternative source-protection license-management python3.14 python3.13 python3.12 python3.11 fastapi django flask pydantic click sqlalchemy llm-tools mcp mcp-server claude-code cursor github-copilot codebuddy windsurf ai-native ai-friendly reverse-mapping unmap deobfuscation stack-trace debuggable provenance cyclonedx sbom dependency-hallucination slopsquatting obfuscate-before-shipping

Metadata

Release files for pyobfus 0.5.32

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pyobfus 0.5.32
File	Size	Uploaded
pyobfus-0.5.32.tar.gz	345.4 kB	Oct 7, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for pyobfus 0.5.32
File	Interpreter	ABI	Platform	Reset
pyobfus-0.5.32-py3-none-any.whl 243.1 kB Oct 7, 2026	Python 3	none	any	Details

Total release size: 588.5 kB

Release files / pyobfus-0.5.32.tar.gz

Download URL	pyobfus-0.5.32.tar.gz
Size	345.4 kB
Tags	Source
SHA-256 checksum How to use checksums	`0ec540994ee2701fe2c04334197bec29f864b4081a2569340331c83e70d132f2`
BLAKE2b-256 checksum How to use checksums	`f07c8b49bfb8cb1e3c05990dfb8939697288b356d854f40597ead70b9f3608e7`
Upload date	Oct 7, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/zhurong2020/pyobfus
Publishing commit: github.com/zhurong2020/pyobfus/tree/3d06873675e295866b9ebf6d5f1e4e1af0fc1512

Workflow

Publishing configuration: github.com/zhurong2020/pyobfus/blob/3d06873675e295866b9ebf6d5f1e4e1af0fc1512/.github/workflows/release.yml
Publishing logs: github.com/zhurong2020/pyobfus/actions/runs/37620030266/attempts/1

Artifact

Subject: pyobfus-0.5.32.tar.gz
SHA-256 checksum: 0ec540994ee2701fe2c04334197bec29f864b4081a2569340331c83e70d132f2 Verifying attestations

Release files / pyobfus-0.5.32-py3-none-any.whl

Download URL	pyobfus-0.5.32-py3-none-any.whl
Size	243.1 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`1431ea8aba306a474a134f1fef7db378d1c6a6b3c3dd0103f4a8ed7879509cbc`
BLAKE2b-256 checksum How to use checksums	`09363a306be1dac5c0be6fa883871c9e5f7f0f57e7b781fede0b704ddbc8e6be`
Upload date	Oct 7, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/zhurong2020/pyobfus
Publishing commit: github.com/zhurong2020/pyobfus/tree/3d06873675e295866b9ebf6d5f1e4e1af0fc1512

Workflow

Publishing configuration: github.com/zhurong2020/pyobfus/blob/3d06873675e295866b9ebf6d5f1e4e1af0fc1512/.github/workflows/release.yml
Publishing logs: github.com/zhurong2020/pyobfus/actions/runs/37620030266/attempts/1

Artifact

Subject: pyobfus-0.5.32-py3-none-any.whl
SHA-256 checksum: 1431ea8aba306a474a134f1fef7db378d1c6a6b3c3dd0103f4a8ed7879509cbc Verifying attestations