Home¶
A pyrig plugin to build executables.
Overview¶
pyrig-executables turns a pyrig-managed project into standalone executables and publishes them with every GitHub release. Installed as a development dependency, it plugs into pyrig's config-generation and tooling system: the entry point, the icon, the build script and tooling, and the release workflow steps needed to compile and attach a per-OS binary are scaffolded, validated, and kept in sync automatically. This page describes each piece; see the API Reference for the generated, code-level documentation.
No tokens or secrets are required — the release workflow authenticates with the
automatic GITHUB_TOKEN. After pyrig sync you may need to fix up the badges in
README.md and docs/index.md once. The pyinstaller and pillow build
dependencies are added for you, so you can also build locally.
It builds on the pyrig-resources plugin, which provides the resources package the icon lives in and that is bundled into the executable.
Components¶
Executable builder¶
ExecutableBuilder wraps PyInstaller. It builds the command that compiles a
single-file (--onefile) executable, applies the icon, and bundles the
project's resources package via --collect-data. It declares pyinstaller and
pillow as development dependencies, excludes the build artifacts (dist/,
*.spec, build/) from version control, and contributes a badge showing the
cumulative download count of the release binaries.
Build script¶
BuildExecutableConfigFile generates build-executable.sh at the project root.
The script runs the executable builder via uv and names the binary
<project-name>-<platform-suffix>.
Run it from the project root after pyrig sync:
Override collect_all_modules or collect_data_modules on
BuildExecutableConfigFile to bundle additional modules into the executable:
--collect-all for modules that ship submodules or binaries alongside their
data, --collect-data for known pure-data packages.
Entry point¶
MainConfigFile scaffolds a main.py containing a main function and an
if __name__ == "__main__" guard — the target the executable is built from.
Validation only checks that the text def main and the guard are present, so your
own entry point is preserved.
Icon¶
IconConfigFile copies the plugin's bundled default icon.png into the
project's resources package. The build passes it to pyinstaller --icon, which
converts it to the per-OS format (.ico on Windows, .icns on macOS; ignored
on Linux). It is created only when missing, so any icon you drop in is kept.
Executable workflow¶
ExecutableWorkflowConfigFile generates the reusable executable.yml workflow,
called by release. Its build matrix runs bash build-executable.sh on Linux,
Windows, and macOS and uploads each binary as an artifact. PyInstaller cannot
cross-compile, so each binary is built on its target platform. Release's publish
job waits for the workflow, downloads the binaries, and attaches them to the
GitHub release alongside the changelog.
Run command¶
run is a CLI command, invoked as pyrig-executables run, that executes your
project's main.py as the __main__ module — the same way the built executable
runs it. It resolves and runs the entry point of whichever project invokes it,
so local runs mirror the shipped binary.
API Reference¶
For class- and method-level details, see the API Reference, which is generated automatically from the source.