Skip to content

How To: Protect a PyInstaller Application

PyInstaller is the most popular Python packaging tool. PyLocket supports both --onefile and --onedir modes.

Prerequisites

  • PyLocket CLI installed and authenticated (pylocket login)
  • An app registered with PyLocket (pylocket apps create)
  • PyInstaller installed (pip install pyinstaller)

Onefile Mode

PyInstaller --onefile produces a single self-extracting executable.

Build

pyinstaller --onefile myapp.py

This creates dist/myapp (Linux/macOS) or dist/myapp.exe (Windows).

Protect

pylocket protect \
  --app <APP_ID> \
  --artifact dist/myapp.exe \
  --platform win-x64 \
  --python 3.12

Download

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

Output Structure

dist/protected/
├── myapp.exe
├── _pylocket_rt.pyd
└── .pylocket_manifest

Onedir Mode

PyInstaller --onedir produces a directory of files.

Build

pyinstaller --onedir myapp.py

This creates dist/myapp/ containing the executable and all dependencies.

Package for Upload

PyLocket accepts ZIP archives for onedir builds. Compress the output directory:

cd dist
zip -r myapp-onedir.zip myapp/

Protect

pylocket protect \
  --app <APP_ID> \
  --artifact dist/myapp-onedir.zip \
  --platform win-x64 \
  --python 3.12

Download and Extract

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

The protected output preserves the onedir structure with the PyLocket runtime files added.

Using a .spec File

If you use a .spec file for custom PyInstaller configuration, the workflow is the same — just build with the spec file first:

pyinstaller myapp.spec

Then protect the output as shown above.

Common Options

Hidden Imports

If your application uses hidden imports (common with dynamic imports, plugins, etc.), ensure they are included in your PyInstaller build before protecting:

pyinstaller --onefile --hidden-import=my_module myapp.py

PyLocket protects whatever PyInstaller packages. If a module is missing from the PyInstaller output, it will also be missing from the protected output.

Data Files

Non-Python data files (images, configs, etc.) bundled by PyInstaller are not encrypted by PyLocket — only Python bytecode is protected. If you need to protect data files, encrypt them separately at the application level.

Console vs. Windowed

Both --console and --windowed (or --noconsole) modes work with PyLocket:

# Console app
pyinstaller --onefile myapp.py

# Windowed app (no console window)
pyinstaller --onefile --windowed myapp.py

Troubleshooting

Problem Solution
Unsupported artifact type Ensure you are uploading the .exe (Windows), the binary (Linux/macOS), or a .zip of the onedir output
Missing modules at runtime Add --hidden-import flags to your PyInstaller command
Large artifact upload timeout For artifacts over 100 MB, ensure a stable connection. The CLI retries up to 3 times automatically.
Protected app crashes on startup Verify the --python version matches your build environment.

See Also