Launcher

Launcher is a small stable executable that starts and updates a Python desktop app.

You package and sign Launcher when the executable, bundled config, icon, or launcher tooling changes. Your app code ships separately as signed GitHub or GitLab release assets.

That split keeps normal app releases small:

• the launcher executable is the durable file users install;
• the app release archive is the versioned source bundle Launcher downloads, verifies, installs, and runs;
• the signed manifest tells Launcher which archive belongs to each app release.

Minimal Workflow

Initialize an app repository:

uv add --dev wetlands-launcher
uv run launcher init --name MyApp --repository https://github.com/my-org/myapp.git
uv run launcher config check
uv run launcher release keygen

Build the launcher executable when it changes:

uv run --with pyinstaller launcher build
# sign/notarize the built launcher here
uv run launcher build package --version v1.2.3
uv run launcher release create v1.2.3 --notes-text "Release v1.2.3"
uv run launcher build upload --version v1.2.3

Supply PyInstaller through the same uv run invocation so it can import the installed launcher package. The build command rejects a pyinstaller executable that is present only on PATH because it may belong to another Python environment and produce an incomplete launcher.

Use one provider release per version and upload each macOS, Windows, or Linux launcher package as a separate platform-named asset. Each successful launcher build upload updates packaging/launcher/distribution.yml; commit and push that file before building on the next machine. After the final platform upload, update the existing release with links for every recorded platform:

uv run launcher release update-notes v1.2.3 --notes-text "Release v1.2.3"

Publish a normal app-only release:

uv run launcher release create v1.2.3 --notes-text "Release v1.2.3"
uv run launcher release archive v1.2.3
uv run launcher release sign
uv run launcher release verify
uv run launcher release upload

Only run launcher build package and launcher build upload for releases where the launcher executable changed. For ordinary app changes, publish the app archive, manifest, and signature.

Learn More

• Packaging guide
• Configuration guide
• Security guide

Development

uv sync
uv run pytest
uv run ruff check .