Configuration¶
All configuration is done with environment variables.
Project¶
There are 3 ways to configure runtime installation, none of which will occur when disabled.
The project name and version must be known in all cases.
Package index¶
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.
Dependency file¶
You may install your project using a dependency file with the PYAPP_PROJECT_DEPENDENCY_FILE option which should be a local path to the file. In this mode, the project name and version have nothing to do with installation and are just used as metadata.
The following formats are supported:
| Extensions | Description |
|---|---|
.txt.in | This is the requirements file format |
Embedding¶
You may embed the project with the PYAPP_PROJECT_PATH option which should be a path to a wheel ending in .whl or a source distribution ending in .tar.gz.
Note
The project name and version is automatically derived from the metadata files inside.
Features (extras)¶
You may set the PYAPP_PROJECT_FEATURES option to select optional dependency groups that would usually be passed to installers within square brackets after the package name e.g. pkg[foo,bar]. In that example, you would set PYAPP_PROJECT_FEATURES to foo,bar.
This also works when embedding the project.
Execution mode¶
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) |
PYAPP_EXEC_SCRIPT | This is a path to a script to embed in the binary and run |
PYAPP_EXEC_NOTEBOOK | This is a path to a Jupyter notebook (.ipynb file) to embed in the binary and run |
If none are set then the PYAPP_EXEC_MODULE option will default to the value of PYAPP_PROJECT_NAME with hyphens replaced by underscores.
GUI¶
If you are packaging a graphical user interface (GUI), you can set PYAPP_IS_GUI to true or 1.
On Windows, this will use pythonw.exe instead of python.exe to execute the application, which avoids a console window from appearing. Running a GUI application with pythonw.exe means that all stdout and stderr output from your GUI will be discarded.
Otherwise, the application will execute as usual. PyApp will run your GUI by spawning a new process, such that the console window that runs the application terminates after successful spawning.
Even when PYAPP_IS_GUI is enabled you can still run the application from the command line. Furthermore, PyApp-specific logic (e.g. installation and setup) will still display a console window with status messages.
Note
On macOS, the console by default does not automatically close when processes have terminated (however it can be closed manually without interferring with the GUI). The default console behavior can be changed in the user settings to close after the last process terminates successfully.
Python distribution¶
Known¶
Setting the PYAPP_PYTHON_VERSION option 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 CPython.
CPython¶
| ID |
|---|
3.7 |
3.8 |
3.9 |
3.10 |
3.11 |
3.12 |
The source for pre-built distributions is the python-build-standalone project.
Some distributions have variants that may be configured with the PYAPP_DISTRIBUTION_VARIANT option:
| Platform | Options |
|---|---|
| Linux |
|
PyPy¶
| ID |
|---|
pypy2.7 |
pypy3.9 |
pypy3.10 |
The source of distributions is the PyPy project.
Custom¶
You 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 correct runtime behavior.
Format¶
The following formats are supported for the PYAPP_DISTRIBUTION_FORMAT option, with the default chosen based on the ending of the source URL:
| Format | Extensions | Description |
|---|---|---|
tar|bzip2 |
| A tar file with bzip2 compression |
tar|gzip |
| A tar file with gzip compression |
tar|zstd |
| A tar file with Zstandard compression |
zip |
| A ZIP file with DEFLATE compression |
Python location¶
You 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.
Site packages location¶
You may set the relative path to the site-packages directory after unpacking the archive with the PYAPP_DISTRIBUTION_SITE_PACKAGES_PATH option. The default is Lib\site-packages on Windows and lib/python<ID>/site-packages on all other platforms where <ID> is the distribution ID is defined.
pip availability¶
You may indicate whether pip is already installed by setting the PYAPP_DISTRIBUTION_PIP_AVAILABLE option to true or 1. This elides the check for installation when upgraded virtual environments are enabled.
Embedding¶
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 can set the PYAPP_DISTRIBUTION_PATH option to use a local path rather than fetching the source, which implicitly enables embedding. The local archive should be similar to the default distributions in that there should be a Python interpreter ready for use.
pip¶
These options have no effect when the project installation is disabled.
Externally managed¶
You may set the PYAPP_PIP_EXTERNAL option to true or 1 to use the standalone versions of pip rather than whatever the distribution provides.
By default, the latest version is used. You may use a specific X.Y.Z version by setting the PYAPP_PIP_VERSION option.
Tip
This provides a significant installation speed up when full isolation is not enabled.
Extra arguments¶
You may set the PYAPP_PIP_EXTRA_ARGS option to provide extra arguments to the pip install command at runtime when installing or updating the project e.g. --only-binary :all: --index-url URL.
Allowing configuration¶
You may set the PYAPP_PIP_ALLOW_CONFIG option to true or 1 to allow the use of environment variables and other configuration at runtime.
Full isolation¶
You may set the PYAPP_FULL_ISOLATION option to true or 1 to provide each installation with a full copy of the distribution rather than a virtual environment.
Virtual environments¶
When full isolation is not enabled, you may set the PYAPP_UPGRADE_VIRTUALENV option to true or 1 to create virtual environments with virtualenv rather than the standard library's venv module.
Skipping project installation¶
You may set the PYAPP_SKIP_INSTALL option to true or 1 to skip installing the project in the distribution. This allows for entirely predefined distributions and thus no network calls at runtime if used in conjunction with distribution embedding.
Installation indicator¶
The environment variable that is used for detection may be set to the path of the executable at runtime if you set the PYAPP_PASS_LOCATION option to true or 1. This is useful if your application wishes to in some way manage itself.
Management command¶
You may set the PYAPP_SELF_COMMAND option to override the default name (self) of the management command group. Setting this to none effectively disables the use of management commands.
When enabled, the value will be available at runtime as the PYAPP_COMMAND_NAME environment variable.
Metadata template¶
You may set a custom template used to output metadata with the PYAPP_METADATA_TEMPLATE option which supports the following placeholders:
| Placeholder | Description |
|---|---|
{project} | The normalized project name |
{version} | The currently installed version of the project |
The default template is {project} v{version} if this option is unset.
This is useful for setting custom commands for the Starship prompt. The following example configuration assumes that the built executable has been renamed to foo:
format = """
+ body[data-md-color-scheme="slate"] .gslide-desc { color: var(--md-default-fg-color);} Configuration¶
All configuration is done with environment variables.
Project¶
There are 3 ways to configure runtime installation, none of which will occur when disabled.
The project name and version must be known in all cases.
Package index¶
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.
Dependency file¶
You may install your project using a dependency file with the PYAPP_PROJECT_DEPENDENCY_FILE option which should be a local path to the file. In this mode, the project name and version have nothing to do with installation and are just used as metadata.
The following formats are supported:
Extensions Description .txt
.inThis is the requirements file format
Embedding¶
You may embed the project with the PYAPP_PROJECT_PATH option which should be a path to a wheel ending in .whl or a source distribution ending in .tar.gz.
Note
The project name and version is automatically derived from the metadata files inside.
Features (extras)¶
You may set the PYAPP_PROJECT_FEATURES option to select optional dependency groups that would usually be passed to installers within square brackets after the package name e.g. pkg[foo,bar]. In that example, you would set PYAPP_PROJECT_FEATURES to foo,bar.
This also works when embedding the project.
Execution mode¶
The following options are mutually exclusive:
Option Description PYAPP_EXEC_MODULEThis is the name of the module to execute via python -m <MODULE> PYAPP_EXEC_SPECThis is an object reference to execute e.g. pkg.foo:cli PYAPP_EXEC_CODEThis is arbitrary code to run via python -c <CODE> (the spec option uses this internally) PYAPP_EXEC_SCRIPTThis is a path to a script to embed in the binary and run PYAPP_EXEC_NOTEBOOKThis is a path to a Jupyter notebook (.ipynb file) to embed in the binary and run
If none are set then the PYAPP_EXEC_MODULE option will default to the value of PYAPP_PROJECT_NAME with hyphens replaced by underscores.
GUI¶
If you are packaging a graphical user interface (GUI), you can set PYAPP_IS_GUI to true or 1.
On Windows, this will use pythonw.exe instead of python.exe to execute the application, which avoids a console window from appearing. Running a GUI application with pythonw.exe means that all stdout and stderr output from your GUI will be discarded.
Otherwise, the application will execute as usual. PyApp will run your GUI by spawning a new process, such that the console window that runs the application terminates after successful spawning.
Even when PYAPP_IS_GUI is enabled you can still run the application from the command line. Furthermore, PyApp-specific logic (e.g. installation and setup) will still display a console window with status messages.
Note
On macOS, the console by default does not automatically close when processes have terminated (however it can be closed manually without interferring with the GUI). The default console behavior can be changed in the user settings to close after the last process terminates successfully.
Python distribution¶
Known¶
Setting the PYAPP_PYTHON_VERSION option 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 CPython.
CPython¶
ID 3.7 3.8 3.9 3.10 3.11 3.12
The source for pre-built 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)v4
PyPy¶
ID pypy2.7 pypy3.9 pypy3.10
The source of distributions is the PyPy project.
Custom¶
You 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 correct runtime behavior.
Format¶
The following formats are supported for the PYAPP_DISTRIBUTION_FORMAT option, with the default chosen based on the ending of the source URL:
Format Extensions Description tar|bzip2.tar.bz2.bz2
A tar file with bzip2 compression tar|gzip.tar.gz.tgz
A tar file with gzip compression tar|zstd.tar.zst.tar.zstd
A tar file with Zstandard compression zip.zip
A ZIP file with DEFLATE compression
Python location¶
You 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.
Site packages location¶
You may set the relative path to the site-packages directory after unpacking the archive with the PYAPP_DISTRIBUTION_SITE_PACKAGES_PATH option. The default is Lib\site-packages on Windows and lib/python<ID>/site-packages on all other platforms where <ID> is the distribution ID is defined.
pip availability¶
You may indicate whether pip is already installed by setting the PYAPP_DISTRIBUTION_PIP_AVAILABLE option to true or 1. This elides the check for installation when upgraded virtual environments are enabled.
Embedding¶
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 can set the PYAPP_DISTRIBUTION_PATH option to use a local path rather than fetching the source, which implicitly enables embedding. The local archive should be similar to the default distributions in that there should be a Python interpreter ready for use.
UV¶
You may set the PYAPP_UV_ENABLED option to true or 1 to use UV for virtual environment creation and project installation.
Version¶
You may use a specific X.Y.Z version by setting the PYAPP_UV_VERSION option.
By default, a version of UV that has already been downloaded by a PyApp application is used. If UV has not yet been downloaded then the latest version is used.
Only bootstrap¶
You may set the PYAPP_UV_ONLY_BOOTSTRAP option to true or 1 to only use UV for virtual environment creation and continue using pip for project installation.
pip¶
These options have no effect when the project installation is disabled.
Externally managed¶
You may set the PYAPP_PIP_EXTERNAL option to true or 1 to use the standalone versions of pip rather than whatever the distribution provides.
By default, the latest version is used. You may use a specific X.Y.Z version by setting the PYAPP_PIP_VERSION option.
Tip
This provides a significant installation speed up when full isolation is not enabled.
Extra arguments¶
You may set the PYAPP_PIP_EXTRA_ARGS option to provide extra arguments to the pip install command at runtime when installing or updating the project e.g. --only-binary :all: --index-url URL.
Allowing configuration¶
You may set the PYAPP_PIP_ALLOW_CONFIG option to true or 1 to allow the use of environment variables and other configuration at runtime.
Full isolation¶
You may set the PYAPP_FULL_ISOLATION option to true or 1 to provide each installation with a full copy of the distribution rather than a virtual environment.
Virtual environments¶
When full isolation is not enabled, you may set the PYAPP_UPGRADE_VIRTUALENV option to true or 1 to create virtual environments with virtualenv rather than the standard library's venv module.
Skipping project installation¶
You may set the PYAPP_SKIP_INSTALL option to true or 1 to skip installing the project in the distribution. This allows for entirely predefined distributions and thus no network calls at runtime if used in conjunction with distribution embedding.
Installation indicator¶
The environment variable that is used for detection may be set to the path of the executable at runtime if you set the PYAPP_PASS_LOCATION option to true or 1. This is useful if your application wishes to in some way manage itself.
Management command¶
You may set the PYAPP_SELF_COMMAND option to override the default name (self) of the management command group. Setting this to none effectively disables the use of management commands.
When enabled, the value will be available at runtime as the PYAPP_COMMAND_NAME environment variable.
Metadata template¶
You may set a custom template used to output metadata with the PYAPP_METADATA_TEMPLATE option which supports the following placeholders:
Placeholder Description {project}The normalized project name {version}The currently installed version of the project
The default template is {project} v{version} if this option is unset.
This is useful for setting custom commands for the Starship prompt. The following example configuration assumes that the built executable has been renamed to foo:
format = """
...
${custom.foo}\
...
@@ -24,4 +24,4 @@
# shell = ["cmd", "/C"]
## Other
# shell = ["sh", "--norc"]
-