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.12, 3.13, or 3.14 (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 <X.Y.Z>

where <X.Y.Z> is the installed version. Compare it against the latest release on PyPI.

Verify your install

After installing, confirm the version matches the latest on PyPI:

pylocket --version

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

Or authenticate via your browser (recommended if you use 2FA or a password manager):

pylocket login --sso

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 (a UUID, e.g., 3f8a1c22-9b4e-4d17-a6f0-2c5e7d90b114). Save this ID; you will use it in every protect command.

Note: --platform records a single informational platform target on the app; the platform that actually applies is set per build with protect --platform.

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). On Linux and macOS the onefile output has no extension, so rename it to myapp.elf before upload (the .elf name is only a transport convention; the engine reads the real format from the file contents). 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 Confirm the install and locate the entry-point script with python -m pip show -f pylocket, then add that scripts directory to your PATH. If you installed inside a virtual environment, activate it first.
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.