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

Release commands read the static [project].version from the TOML file named by configuration and use that exact value as the release tag. Set release.tag_template: "v{version}" only when the repository deliberately uses prefixed tags. Explicit version arguments remain available for dynamic or non-TOML projects and must match inferred values when both are present.

Build the launcher executable when it changes:

uv run --with pyinstaller launcher build
# sign/notarize the built launcher here
uv run launcher build package
uv run launcher release create --tag --push --notes-text "Release 1.2.3"
uv run launcher release archive
uv run launcher release sign
uv run launcher release verify
uv run launcher release upload
uv run launcher build upload

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 --notes-text "Release 1.2.3"

Publish a normal app-only release:

uv run launcher release create --tag --push --notes-text "Release 1.2.3"
uv run launcher release archive
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 .