Skip to content

Getting Started

This guide walks you through installing PyLocket and protecting your first Python application. By the end, you will have a protected executable that requires a license key to run.

Time required: ~5 minutes

Prerequisites

Requirement Version Notes
Python 3.9 or later (3.12 recommended) python.org/downloads
pip Latest Bundled with Python
Internet connection — Required for account creation and artifact upload

You do not need Docker, Rust, or Node.js to use PyLocket as a client. Those are only required if you are contributing to PyLocket itself.

Step 1: Install the CLI

Install the PyLocket command-line tool from PyPI:

pip install pylocket

Verify the installation:

pylocket --version

You should see output like:

pylocket, version 1.0.0

Tip: We recommend installing PyLocket inside a virtual environment to avoid dependency conflicts:

python -m venv .venv
source .venv/bin/activate   # macOS/Linux
.venv\Scripts\activate      # Windows
pip install pylocket

Step 2: Create an Account

Register for a free PyLocket developer account:

pylocket login

If you do not have an account, the CLI will prompt you to create one. You can also register through the Developer Portal.

After logging in, your credentials are stored locally at ~/.pylocket/credentials. You will not need to log in again on this machine unless the token expires.

Step 3: Register Your Application

Before you can protect an artifact, you need to register an application:

pylocket apps create --name "MyApp" --platform win-x64

This returns an App ID (e.g., app_a1b2c3d4). Save this — you will use it in every protect command.

Note: You can register multiple platforms at once:

pylocket apps create --name "MyApp" --platform win-x64 linux-x64 mac-arm64

To list your registered apps at any time:

pylocket apps list

Step 4: Protect Your Application

Assume you have built your Python application into an executable using PyInstaller:

pyinstaller --onefile myapp.py

This produces dist/myapp (or dist/myapp.exe on Windows). Now protect it:

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

PyLocket uploads your artifact, applies military-grade encryption at the function level, injects the license-checking bootstrap, and returns a Build ID.

Check the build status:

pylocket status --build <BUILD_ID>

When the status shows READY, download the protected output:

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

Your protected application is now in dist/protected/.

Step 5: Test the Protected App

Run the protected application:

./dist/protected/myapp.exe

The app will prompt for a license key. Since you have not created any licenses yet, it will fail activation — this is expected.

To test with a real license, see the Licensing Tutorial.

What Just Happened?

Here is what PyLocket did behind the scenes:

  1. Uploaded your artifact to PyLocket's secure cloud storage (encrypted at rest)
  2. Scanned the artifact for malware (if enabled)
  3. Extracted all Python bytecode from the packaged application
  4. Encrypted each function body individually with military-grade encryption
  5. Generated a cryptographically signed protection manifest
  6. Injected a bootstrap module that loads the native runtime and verifies the manifest
  7. Bundled the native runtime into the output
  8. Packaged everything into a new protected artifact

At runtime, functions are decrypted on-demand (one at a time) and securely zeroed from memory after execution.

Next Steps

Goal Guide
Understand the full protection workflow Basic Tutorial
Explore multi-platform builds and CI/CD integration Advanced Tutorial
Set up licensing and deliver to customers Licensing Tutorial
Publish for Windows, macOS, and Linux Multi-OS Publishing
Protect a specific packaging format How-To Guides

Troubleshooting

Problem Solution
pylocket: command not found Ensure the install directory is on your PATH. Try python -m pylocket --version.
Authentication failed Run pylocket login again. Your token may have expired.
Unsupported artifact type PyLocket supports .py, .pyz, .pyw, .whl, .egg, .zip, .tar.gz, .tgz, .tar.bz2, and executables from PyInstaller, cx_Freeze, and Briefcase.
Build status stuck at PENDING The protection queue may be under load. Wait a few minutes and check again. If it persists for more than 10 minutes, contact support.
HTTP 402 Payment Required You have exceeded the free tier (10 downloads per app). Add a payment method in the Developer Portal.

For more error details, see Error Messages.