Skip to content

How To: Control Which Modules Are Protected

This guide explains how PyLocket decides which Python modules to protect and how you can override that behavior.

Default Behavior: Automatic Module Classification

PyLocket automatically classifies every module in your artifact as either user code (protected) or dependency code (skipped). You do not need to configure anything for typical projects — PyLocket protects your code and leaves everything else untouched.

What Gets Protected by Default

  • Your application's entry module (the main script)
  • All user-written helper modules reachable from the entry module
  • Standalone .py files that are part of your project

What Is Automatically Skipped

  • Python standard library modules (os, sys, json, pathlib, etc.)
  • PyInstaller internals (pyimod, pyiboot, pyi_rth_*)
  • Common third-party packages (requests, flask, django, pydantic, click, rich, tqdm, setuptools, pip, certifi, urllib3, etc.)
  • C extension modules (.pyd, .so files compiled from C/Cython)

This means PyLocket protects only your proprietary code by default — the parts that contain your business logic and intellectual property.

Why You Should Not Protect Every Module

Do not force-include third-party libraries

Protecting third-party dependencies is unnecessary and can cause problems:

  • Increased build time and artifact size — encrypting thousands of library functions adds overhead with no security benefit
  • Potential runtime errors — some libraries use reflection, dynamic imports, or introspection that may not work correctly when function bodies are replaced with stubs
  • No IP value — third-party libraries are already publicly available; encrypting them does not protect your intellectual property

Focus protection on the code that is uniquely yours: your application logic, algorithms, business rules, and proprietary modules.

Overriding Module Selection

For advanced use cases, you can force-include or force-exclude specific modules using environment variables. These overrides take priority over all automatic classification.

Force-Include Modules

Use PYLOCKET_FORCE_INCLUDE to protect modules that PyLocket would otherwise skip:

PYLOCKET_FORCE_INCLUDE=my_utils,my_helpers pylocket protect \
  --app <APP_ID> \
  --artifact dist/myapp.exe \
  --platform win-x64 \
  --python 3.12

Use case: You have a helper module that PyLocket's heuristics incorrectly classify as a third-party dependency.

Force-Exclude Modules

Use PYLOCKET_FORCE_EXCLUDE to skip modules that PyLocket would otherwise protect:

PYLOCKET_FORCE_EXCLUDE=my_debug_module,my_test_helpers pylocket protect \
  --app <APP_ID> \
  --artifact dist/myapp.exe \
  --platform win-x64 \
  --python 3.12

Use case: You have a debug or diagnostic module that you want to leave unprotected for troubleshooting, or a module that uses heavy introspection and does not work well when protected.

Environment Variable Format

Variable Format Description
PYLOCKET_FORCE_INCLUDE Comma-separated module names Modules to always protect
PYLOCKET_FORCE_EXCLUDE Comma-separated module names Modules to never protect

Module names should match the Python module name (not the file path). For example, if your file is src/my_utils.py, the module name is my_utils.

Using in CI/CD

Set the environment variables in your CI/CD pipeline:

# GitHub Actions example
- name: Protect application
  env:
    PYLOCKET_TOKEN: ${{ secrets.PYLOCKET_TOKEN }}
    PYLOCKET_FORCE_EXCLUDE: debug_tools,test_fixtures
  run: pylocket protect --app $APP_ID --artifact dist/myapp.exe --platform win-x64 --python 3.12

Classification Priority

When PyLocket evaluates a module, it follows this priority order:

  1. Force-include override → Module is protected
  2. Force-exclude override → Module is skipped
  3. Entry module → Protected
  4. Not reachable from entry module → Skipped
  5. Standard library module → Skipped
  6. PyInstaller / packaging tool internal → Skipped
  7. Known third-party package → Skipped
  8. Standalone, reachable user module → Protected

Tips

  • Start with defaults — PyLocket's automatic classification works correctly for the vast majority of projects. Only use overrides if you encounter a specific issue.
  • Check your build output — The protection log lists which modules were protected and which were skipped, so you can verify the classification.
  • Separate your code from dependencies — Keeping your project structure clean (your code in a distinct package, dependencies installed via pip) helps PyLocket classify modules accurately.

See Also