Skip to content

Home

CI CD ProjectTester SecurityPracticesChecker Best Practices Baseline

ByteOrderMarkerFormatter CICDLinter CICDSecurityChecker CaseConflictChecker CodeAnalyzer DeadCodeChecker DependencyChecker EndOfFileFormatter EndOfLineFormatter FuzzTester JSONFormatter JSONLinter LargeFileChecker MarkdownLinter MergeConflictChecker ModuleTestNamingChecker PythonLinter PythonOrderLinter SecretsChecker SecurityChecker ShellFormatter ShellLinter SpellChecker TOMLLinter TrailingWhitespaceFormatter TypeChecker XMLLinter YAMLLinter

PackageManager Pyrigger RemoteVersionController VersionControlHookManager VersionController

DocsBuilder ExecutableBuilder PackageIndex ProgrammingLanguage License


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.

uv add pyrig-executables --dev
uv run pyrig sync

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:

bash build-executable.sh

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.