pyobfus — the Python obfuscator

pyobfus (pronounced as "Python obfuscator") is a modern, AST-based python-obfuscator / code-obfuscator with framework-aware presets, reverse stack-trace mapping for AI-assisted debugging, and a machine-readable JSON CLI designed for Claude Code, Cursor, and MCP agents. A transparent, open-source alternative to PyArmor.

A Python code obfuscator built with AST-based transformations. Supports Python 3.8 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.

🤖 New in v0.4.0 — AI-native features

• pyobfus --check src/ — pre-flight risk scan: detects eval/exec, dynamic attribute access, and framework reflection points before you obfuscate. JSON output with an ai_hint telling your AI assistant what to run next.
• 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.
• Framework-aware presets — --preset fastapi | django | flask | pydantic | click | sqlalchemy with built-in exclusions for dispatch methods, decorators, ORM fields, migrations, and dependency-injection parameters.
• 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 (v0.2.0): 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

• 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)

🔒 Pro Edition (Available Now)

The following advanced features are available with a Pro license:

• String Encryption (

... View full README on GitHub