Skip to content

Protecting Raw Python Scripts

This guide covers protecting raw .py, .pyz, and .pyw files with PyLocket. This is a niche use case — for most scenarios, we recommend building a standalone executable first.

End users need Python installed

Unlike .exe or .app artifacts, protected Python scripts require Python on the end user's machine. If you are distributing to end users who may not have Python, use PyInstaller, cx_Freeze, or Briefcase to create a standalone executable, then protect that instead.

How It Works

A raw .py file cannot run standalone after protection. PyLocket protects .py files by:

  1. Compiling them to .pyc bytecode
  2. Encrypting each function body with AES-256-GCM
  3. Replacing function bodies with stubs that call _pylocket_rt.invoke()
  4. Repacking everything into a ZIP archive with the runtime and manifest

The protected output is not a standalone .py file — it is a repacked artifact (ZIP) containing:

File Purpose
Encrypted .pyc modules Your code with function bodies replaced by stubs
_pylocket_rt.pyd / .so Native runtime that decrypts functions on demand
.pylocket_manifest Encrypted metadata for license validation
Bootstrap module Loader that initializes the runtime and import hooks

The end user needs Python installed and a valid license key to run the protected application.

When to Use This

Raw .py protection is appropriate when:

  • Developer tools / CLI apps — your users are developers who already have Python
  • Internal distribution — within an organization where Python is standard
  • Python libraries — scripts distributed as part of a larger Python project (consider wheels instead)
  • Rapid prototyping — testing protection before setting up a full build pipeline

For all other cases, especially distributing to end users:

Target Audience Recommended Approach
End users (no Python) PyInstaller → .exe / binary
macOS end users Briefcase → .app bundle
Python developers Wheel → .whl (pip installable)
Internal teams Raw .py (this guide) or ZIP

Step 1: Prepare Your Script

Package your .py file(s) into a ZIP archive:

# Single script
zip myapp.zip myapp.py

# Multiple scripts with dependencies
zip -r myapp.zip myapp.py utils.py config.py

For .pyz (zipapp) files:

python -m zipapp myproject -o myapp.pyz -m "myapp:main"

Step 2: Upload and Protect

pylocket protect \
  --app <APP_ID> \
  --artifact myapp.zip \
  --platform cross_platform \
  --python 3.12
  1. Go to Apps → select your app → Upload Build
  2. Select your .py, .pyz, or .zip file
  3. Set Artifact Type to .py, .pyz, or .zip
  4. Set Platform to Cross-platform
  5. Click Upload Build

Step 3: Distribute to Users

After protection completes, download the protected artifact:

pylocket fetch --build <BUILD_ID> --out dist/protected/

The protected output is a ZIP archive. Distribute it to users with instructions:

# End user extracts and runs:
unzip myapp-protected.zip -d myapp/
cd myapp/
python myapp.py
# → License prompt appears on first run

The _pylocket_rt native extension and .pylocket_manifest must be in the same directory as the script.

Limitations

Limitation Details
Requires Python End user must have Python installed (same major.minor version used during protection)
Not a standalone executable The output is a ZIP archive, not a double-clickable application
Native runtime required The _pylocket_rt extension must be present alongside the script
Platform-specific runtime The native extension is compiled for a specific OS — distribute the correct one

Next Steps

Topic Link
Build standalone executables instead PyInstaller, Briefcase
Protect a wheel for pip distribution Wheel
Protect a ZIP archive ZIP
How protection works under the hood How Protection Works