Skip to main content

Tutorial

This walkthrough takes a small Python package from plain source to a protected, runnable distribution. It assumes you've completed Installation and authorized this machine with obfy login then obfy register (or an offline activation — see Seats and devices). obfy build is refused until the machine holds a seat.

1. Start with a project​

Say you have a package you want to protect:

myapp/
├── run.py
├── core.py
└── utils.py

2. Build a protected distribution​

Run one command, pointing --src at your code and --out at a fresh directory:

obfy build --src ./myapp --out ./dist --python python3
Point --src at your code, not your repo root

Every non-.py file under --src is copied into the dist so it runs in place. If --src is a repo root, files like .env, credentials, or keys get copied too. Point --src at your code package, or build from a code-only staging tree.

3. Inspect the output​

./dist is a 1:1 mirror of ./myapp:

dist/
├── run.py            # tiny self-activating stub
├── core.py           # stub
├── utils.py          # stub
├── code.key          # AES-256-GCM key (do NOT commit or ship — see below)
└── __obfy__/         # encrypted payloads + bundled native runtime

Each .py is now a small stub; the real code lives encrypted in __obfy__/*.obfy. The native runtime is bundled in __obfy__/, so there's nothing extra to install on the target.

4. Run it​

Run it exactly as you ran the original — no sys.path edits, no manual bootstrap:

python ./dist/run.py

The bundled runtime decrypts each module in memory at import time.

5. Choose a protection level​

The default level is 1 (strip docstrings). Turn the dial up for stronger protection:

obfy build --src ./myapp --out ./dist --level 4

See Obfuscation levels for what each level adds.

6. Protect the key​

By default the build writes code.key into the dist and reads it from there at run time. Never commit code.key, and to keep it out of the shipped dist entirely, delete it after building and supply it out-of-band via the OBFY_KEY environment variable (hex) at run time. See Keys and licensing.

Next steps​