Content
# pyobfus: the Python obfuscator
<p align="center"><img src="https://raw.githubusercontent.com/zhurong2020/pyobfus/main/docs/assets/logo.jpeg" alt="pyobfus Logo" width="180"></p>
<p align="center"><strong>Obfuscate Python before you ship it—and still debug what you shipped.</strong></p>
<p align="center"><a href="https://github.com/zhurong2020/pyobfus/blob/main/README.zh-CN.md">简体中文</a> · <a href="https://zhurong2020.github.io/pyobfus/">Product</a> · <a href="https://pyobfus.readthedocs.io/">Documentation</a> · <a href="https://pypi.org/project/pyobfus/">PyPI</a></p>
[](https://pypi.org/project/pyobfus/)
[](https://pypi.org/project/pyobfus/)
[](https://pyobfus.readthedocs.io/en/latest/)
[-blue.svg)](https://github.com/zhurong2020/pyobfus/blob/main/LICENSE)
[](https://www.python.org/downloads/)
[](https://www.bestpractices.dev/projects/12788)
[](https://doi.org/10.5281/zenodo.20846053)
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.
## 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
```bash
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
# 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](https://pyobfus.readthedocs.io/).
## Minimal example
Input:
```python
def greet(name):
message = f"Hello, {name}!"
return message
print(greet("world"))
```
Run `pyobfus input.py -o output.py`. Representative Community output:
```python
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 project-wide name mangling and import rewriting, 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](https://github.com/zhurong2020/pyobfus/blob/main/docs/EDITION_BOUNDARY_POLICY.md).
## 🔌 Companion MCP server: `pyobfus-mcp`
Install the MCP server with no API key and no source upload:
```bash
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](https://github.com/zhurong2020/pyobfus/tree/main/pyobfus_mcp)
and its registration in the
[official MCP Registry](https://registry.modelcontextprotocol.io/).
### Agent and editor integrations
- `pyobfus-review` and `pyobfus-protect` skills separate read-only review from
build-producing work. See [skills](https://github.com/zhurong2020/pyobfus/tree/main/skills).
- The [VS Code extension](https://marketplace.visualstudio.com/items?itemName=zhurong2020.pyobfus)
provides inline risk diagnostics and traceback reversal; it is also on
[Open VSX](https://open-vsx.org/extension/zhurong2020/pyobfus).
- [`zhurong2020/pyobfus-action@v1`](https://github.com/marketplace/actions/pyobfus-scan-and-build)
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`](https://github.com/zhurong2020/pyobfus/blob/main/llms.txt), while
contributor instructions live in
[`AGENTS.md`](https://github.com/zhurong2020/pyobfus/blob/main/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:
```bash
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](https://pyobfus.readthedocs.io/) and
[`pyobfus --help`](https://github.com/zhurong2020/pyobfus/blob/main/pyobfus/cli.py)
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:
```bash
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:
```bash
pyobfus-trial start
```
The trial is an honor-system convenience control, not a security boundary.
Visit the [product and purchase page](https://zhurong2020.github.io/pyobfus/#purchase-professional-edition)
for current payment methods, refund terms and purchase steps. After purchase,
use the [license activation guide](https://pyobfus.readthedocs.io/en/latest/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.
- [Threat model](https://pyobfus.readthedocs.io/en/latest/THREAT_MODEL/)
- [Support matrix](https://pyobfus.readthedocs.io/en/latest/SUPPORT_MATRIX/)
- [Release provenance](https://github.com/zhurong2020/pyobfus/blob/main/docs/RELEASE_PROVENANCE_VERIFICATION.md)
- [Security policy](https://github.com/zhurong2020/pyobfus/blob/main/SECURITY.md)
## Comparison and deployment guides
- [Comparison overview](https://pyobfus.readthedocs.io/en/latest/COMPARISON/)
- [vs PyArmor](https://pyobfus.readthedocs.io/en/latest/compare/pyarmor/)
- [vs Nuitka](https://pyobfus.readthedocs.io/en/latest/compare/nuitka/)
- [PyInstaller cookbook](https://pyobfus.readthedocs.io/en/latest/PYINSTALLER_COOKBOOK/)
- [Compiled-packaging cookbook](https://github.com/zhurong2020/pyobfus/blob/main/docs/COMPILED_PACKAGING_COOKBOOK.md)
- [Integration testing](https://pyobfus.readthedocs.io/en/latest/INTEGRATION_TESTING/)
## 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:
- [Project structure](https://pyobfus.readthedocs.io/en/latest/PROJECT_STRUCTURE/)
- [Contributing guide](https://github.com/zhurong2020/pyobfus/blob/main/CONTRIBUTING.md)
- [Developer instructions](https://github.com/zhurong2020/pyobfus/blob/main/AGENTS.md)
- [Changelog](https://github.com/zhurong2020/pyobfus/blob/main/CHANGELOG.md)
## Community and citation
Use [GitHub Issues](https://github.com/zhurong2020/pyobfus/issues) for bugs and
[Discussions](https://github.com/zhurong2020/pyobfus/discussions) for questions
and ideas. Citation metadata is in
[`CITATION.cff`](https://github.com/zhurong2020/pyobfus/blob/main/CITATION.cff),
with archival DOI [10.5281/zenodo.20846053](https://doi.org/10.5281/zenodo.20846053).
Core is Apache-2.0; Professional implementation is proprietary. See
[`LICENSE-NOTICE.md`](https://github.com/zhurong2020/pyobfus/blob/main/LICENSE-NOTICE.md).
Connection Info
You Might Also Like
No recommendations available