Skip to main content

Introduction

Obfy protects Python source by transforming it at build time and decrypting it only in memory at run time. You point the obfy CLI at a package; it produces a protected mirror of that package that you ship in place of the original.

Core concepts​

The CLI (obfy)​

The build-time tool you run on your developer machine or in CI. It discovers every file under your source tree, obfuscates and encrypts the Python modules, and writes a protected distribution. The CLI is also where you authenticate (obfy login) and manage the machine's seat (obfy register).

The runtime (obfy_runtime)​

A native (Rust/PyO3) extension that performs decryption and license checks. It comes with the obfy package, and Obfy bundles it into every distribution, so your end users install nothing extra — only the lean runtime is packaged into your output, never the CLI.

Obfuscation level (--level 0–5)​

A single dial controlling how aggressively your code is transformed. Each level adds to the one below it — from simply encrypting the bytecode (0) up to compiling eligible functions to a clean-room VM so their CPython bytecode never ships (5). See Obfuscation levels.

The protected distribution​

The output of obfy build. It is a 1:1 mirror of your source tree: same file names, same layout. Each .py becomes a tiny self-activating stub; the real code lives encrypted under __obfy__/, alongside the bundled runtime. Non-Python files (templates, static assets, data) are copied across so the dist runs in place.

Seats and devices​

Obfy is licensed per developer seat. obfy login signs you in and obfy register claims a device slot against your organization's seat; obfy build is refused on an unauthorized machine. Air-gapped machines use an offline activation file instead, and CI builds use a separate CI token rather than a developer slot. See Seats and devices.

How it works​

  1. Authorize your machine once with obfy login then obfy register (or an offline activation on an air-gapped machine).
  2. Build a protected distribution: obfy build --src ./app --out ./dist.
  3. Obfy obfuscates each module (per --level), then compiles → marshals → AES-256-GCM encrypts it.
  4. Ship the ./dist mirror. At import time, the bundled native runtime decrypts each module in memory and enforces any license terms.

Next steps​

Proceed to the Installation guide, then work through the Tutorial to protect your first project.