How To: Cross-Platform Builds¶

This guide explains how to protect your application for multiple operating systems and architectures.

Supported Platforms¶

Platform ID	OS	Architecture	File Extension
`win-x64`	Windows	x86_64	`.exe`
`linux-x64`	Linux	x86_64	(none)
`linux-arm64`	Linux	aarch64	(none)
`mac-x64`	macOS	Intel	(none) or `.app`
`mac-arm64`	macOS	Apple Silicon	(none) or `.app`

Strategy¶

Cross-platform protection requires:

Building your application separately on each target platform (or using cross-compilation)
Protecting each platform artifact individually with PyLocket

PyLocket bundles a platform-specific native runtime for each target.

Register All Platforms at Once¶

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

Build Per Platform¶

Option A: Build on Native Hardware¶

Build on each target platform:

# On Windows
pyinstaller --onefile myapp.py
# → dist/myapp.exe

# On Linux x64
pyinstaller --onefile myapp.py
# → dist/myapp

# On macOS ARM
pyinstaller --onefile myapp.py
# → dist/myapp

Option B: CI/CD Matrix Build¶

Use a CI/CD matrix to build on multiple runners:

# GitHub Actions
jobs:
  build:
    strategy:
      matrix:
        include:
          - os: windows-latest
            platform: win-x64
            artifact: dist/myapp.exe
          - os: ubuntu-latest
            platform: linux-x64
            artifact: dist/myapp
          - os: macos-latest
            platform: mac-arm64
            artifact: dist/myapp
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: pip install pyinstaller -r requirements.txt
      - run: pyinstaller --onefile myapp.py
      - uses: actions/upload-artifact@v4
        with:
          name: build-${{ matrix.platform }}
          path: ${{ matrix.artifact }}

Protect Each Platform¶

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

# Linux x64
pylocket protect --app <APP_ID> --artifact dist/myapp --platform linux-x64 --python 3.12

# macOS ARM
pylocket protect --app <APP_ID> --artifact dist/myapp --platform mac-arm64 --python 3.12

Each command produces a separate Build ID. Track them independently.

Platform-Specific Native Runtime¶

The native runtime file name varies by platform:

Platform	Runtime File
Windows	`_pylocket_rt.pyd`
Linux	`_pylocket_rt.so`
macOS	`_pylocket_rt.so`

The correct runtime is automatically bundled during protection. You do not need to manage this manually.

Licensing Across Platforms¶

License keys are platform-independent. A single license key works on any platform for the same app. Device fingerprints are platform-specific, so activating on Windows and macOS counts as two separate devices toward the device limit.

Delivery¶

When you have multiple platforms protected for the same app, the PyLocket delivery page automatically shows labeled download buttons for each available platform (e.g., "Windows", "macOS", "Linux"). Customers see only the platforms you have uploaded builds for.

Tip: For a full end-to-end walkthrough covering building, protecting, and distributing for all three OSes, see the Multi-OS Publishing Tutorial.