Skip to content

Replace with Signed Package

Protection changes your artifact, which invalidates any code signature it had. The Replace with Signed Package flow lets you sign the protected build with your own certificate and upload the signed copy back to PyLocket, so the version your customers download is the trusted, signed one.

When to use it

Use Replace with Signed Package after you have:

  1. Downloaded the protected build from PyLocket.
  2. Signed it with your own certificate (Apple Developer ID for macOS, Authenticode for Windows). See Code Signing.

You then upload the signed file in place of the protected one. PyLocket keeps the same build, license bindings, and download links; only the bytes customers receive change to your signed version.

How to replace a build

  1. Open the Developer Portal, go to your app, and open the Builds page.
  2. Find the protected build and choose Replace with Signed Package.
  3. Select your signed file:
    • Windows: the signed .exe.
    • macOS: the signed .app packaged as .app.zip.
  4. Upload. PyLocket verifies the upload is a signed copy of that exact protected build (same code, only signature data differs) and swaps it in.

It must be the same protected build, just signed

The check confirms your upload is the current protected build with a signature added, not a different or older binary. If you see a "does not appear to be a signed copy of the current protected build" message, you most likely selected an older file or a different binary. Re-download the current protected build, sign that exact file, and upload the result.

macOS: extract and re-archive with ditto, never a third-party archiver

A macOS app bundle only survives a round trip when both directions preserve symlinks, permissions, and every bundled file. Use Apple's built-in tools for both steps, from Terminal:

# 1. Extract the protected download
ditto -x -k Protected.app.zip extracted/

# 2. (sign and notarize the extracted .app)

# 3. Re-archive the signed app (keep the .app.zip name so the upload
#    carries the bundle signal)
ditto -c -k --keepParent YourApp.app YourApp.app.zip

Third-party archivers can silently drop package metadata folders (*.dist-info) from inside the bundle. So can some SIGNING tools: signing apps that "clean" a bundle before signing have been observed deleting *.dist-info directories outright. Those folders look inert but register your app's plugin loaders at runtime - an app missing them still launches and then fails only when the affected feature is used. PyLocket rejects a replacement that lost metadata the protected build carries; the error names the missing folders and repeats these commands.

Run this self-check twice - once right after extracting, and again AFTER signing, before you re-archive and upload:

find YourApp.app -name entry_points.txt

The list must be identical both times. If entries disappear after signing, your signing tool removed them. To recover, copy the real *.dist-info folders back from the extracted original into YourApp.app/Contents/Resources/, re-seal the top level of the bundle (codesign --force --options runtime --sign "YOUR_ID" YourApp.app - the nested signatures your tool already applied stay valid), re-run the check above, then notarize and re-archive. Also report the deletion to the signing tool's developers so it stops happening.

Copy the real folders, not just the shortcuts. Inside a macOS app bundle these folders exist as real directories under Contents/Resources/ with matching symbolic links under Contents/Frameworks/. A copy that brings back only the links leaves them pointing at nothing, which is the same as having no metadata at all.

The "Ready - Signed" badge

Once a signed replacement is accepted, the build's status on the Builds page shows Ready - Signed with a lock icon, instead of the normal Ready. This is your at-a-glance confirmation that customers are downloading a code-signed package.

A build keeps working exactly as before whether or not it is signed. The badge is purely informational; it does not change download links, license behavior, or anything your customers do.

Topic Link
Sign your app Code Signing
Distribute macOS apps Distributing macOS .app bundles
Distribute your app Distribute Your App