PyApp is a CLI wrapper for Python applications that bootstrap themselves at runtime. Each application is configured with environment variables at build time.
For a more streamlined workflow, consider using the built-in app build target of Hatch.
Table of Contents
Select the directory in which to build your application with the --root option:
cargo install pyapp --force --root <DIR>
The executable will be located at <DIR>/bin/pyapp.exe if on Windows or <DIR>/bin/pyapp otherwise.
On the first run of the application:
All subsequent invocations will only check if the unpacked distribution directory exists and nothing else, to maximize CLI responsiveness.
Built applications have a single top-level command group named self and all other invocations will be forwarded to your actual execution logic.
<EXE> self restore
This will wipe the unpacked distribution and start fresh.
<EXE> self update
This will update the project to the latest available version in the currently used distribution.
<EXE> self starship
This displays customized output that may be used by the Starship prompt.
All configuration is done with environment variables.
The desired project name and version are configured with the PYAPP_PROJECT_NAME and PYAPP_PROJECT_VERSION options, respectively. The project name must adhere to PEP 508 and will be normalized during builds according to PEP 503.
The following options are mutually exclusive:
| Option | Description |
| --- | --- |
| PYAPP_EXEC_MODULE | This is the name of the module to execute via python -m <MODULE> |
| PYAPP_EXEC_SPEC | This is an object reference to execute e.g. pkg.foo:cli |
| PYAPP_EXEC_CODE | This is arbitrary code to run via python -c <CODE> (the spec option uses this internally) |
If none are set then the PYAPP_EXEC_MODULE option will default to the value of PYAPP_PROJECT_NAME with hyphens replaced by underscores.
Setting the PYAPP_PYTHON_VERSION option in the form MAJOR.MINOR will determine the distribution used at runtime based on the environment at build time. If unset then the default will be the latest stable minor version of Python.
The default source of relocatable distributions is the python-build-standalone project.
Some distributions have variants that may be configured with the PYAPP_DISTRIBUTION_VARIANT option:
| Platform | Options | | --- | --- | | Linux |
v1v2v3 (default)v4shared (default)staticYou may explicitly set the PYAPP_DISTRIBUTION_SOURCE option which overrides the known distribution settings. The source must be a URL that points to an archived version of the desired Python distribution.
Setting this manually may require you to define extra metadata about the distribution that is required for accurate runtime behavior.
The following compression methods are supported for the PYAPP_DISTRIBUTION_COMPRESSION option, with the default chosen based on the ending of the source URL:
| Method | Extensions | Description |
| --- | --- | --- |
| tar\|gzip |
.tar.gz.tgztar\|zstd | .tar.zst.tar.zstdzip | .zipYou may set the relative path to the Python executable after unpacking the archive with the PYAPP_DISTRIBUTION_PYTHON_PATH option. The default is python.exe on Windows and bin/python3 on all other platforms.
You may set the PYAPP_DISTRIBUTION_EMBED option to true or 1 to embed the distribution in the executable at build time to avoid fetching it at runtime.
You may set a custom command for the Starship prompt with the PYAPP_STARSHIP_PROMPT option which supports the following placeholders:
| Placeholder | Description |
| --- | --- |
| {project} | The normalized project name |
| {version} | The currently installed version of the project |
The default output is {project} v{version} if this option is unset.
The following example configuration assumes that the built executable has been renamed to foo:
```toml format = """ ... ${custom.foo}\ ... $line_break\ ... $character"""
[custom.foo] command = "foo self starship" when = true
```
--pre flag to the update command to allow prereleasesPYAPP_SKIP_INSTALL build time option to skip project installation, allowing for entirely predefined distributions and thus no network calls at runtime if used in conjunction with embeddingPYAPP_PIP_INDEX_URL and PYAPP_PIP_EXTRA_INDEX_URL build time options that correspond to the --index-url and --extra-index-url flags of the pip install command, respectivelyPYAPP_PIP_EXTERNAL build time option that indicates the distribution does not ship with pip and will use its standalone installation (note that this may be the default behavior in future depending on feedback)PyApp is distributed under the terms of any of the following licenses: