How To: Protect a Python Wheel¶

PyLocket can protect .whl (wheel) packages, allowing you to distribute encrypted Python libraries through private package indexes.

Prerequisites¶

PyLocket CLI installed and authenticated
An app registered with PyLocket
A built wheel file (.whl)

Build a Wheel¶

pip install build
python -m build --wheel

This creates a .whl file in dist/:

dist/mylib-1.0.0-py3-none-any.whl

Protect¶

pylocket protect \
  --app <APP_ID> \
  --artifact dist/mylib-1.0.0-py3-none-any.whl \
  --platform linux-x64 \
  --python 3.12

Download¶

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

The output is a new .whl file with encrypted bytecode.

Installing the Protected Wheel¶

End-users install the protected wheel with pip:

pip install mylib-1.0.0-py3-none-any.whl

The PyLocket runtime is bundled inside the wheel. When the library is imported, the bootstrap code activates and validates the license.

Private Package Index¶

For automated distribution, host the protected wheel on a private PyPI server:

# Upload to a private index
twine upload --repository private dist/protected/mylib-1.0.0-py3-none-any.whl

End-users install from your private index:

pip install --index-url https://pypi.yourcompany.com/simple/ mylib

Auto-Initialization via `init.py`¶

For the best end-user experience, add a bootstrap import to your package's __init__.py before protecting the wheel:

# mylib/__init__.py
try:
    import _pylocket_bootstrap  # noqa: F401  — activates PyLocket runtime
except ImportError:
    pass  # Not protected (development environment)

from mylib.core import my_function  # Your public API

With this pattern, end-users simply install and import — no extra setup required:

pip install mylib-1.0.0-py3-none-any.whl

from mylib import my_function  # Works transparently

The bootstrap import activates the PyLocket runtime, enabling transparent use of protected modules.

Best practice for library distribution

Protecting a wheel with an auto-initializing __init__.py is the recommended approach for distributing protected Python libraries. End-users get a standard pip install experience with no knowledge of the protection layer.

Notes¶

All .pyc files inside the wheel are encrypted. Non-Python files (data, configs) are passed through unchanged.
The protected wheel includes the PyLocket runtime as a bundled extension module.
The --python version should match the target environment where the wheel will be installed.
Platform-specific wheels (cp312-cp312-manylinux) are also supported.