Python distribution configuration¶

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`
`3.13`

The source for pre-built distributions is the python-build-standalone project.

Variants¶

Some distributions have variants that may be configured. Options may be combined.

Option	Platforms	Allowed values
`PYAPP_DISTRIBUTION_VARIANT_CPU`	Linux	`v1` `v2` `v3` (default) `v4`
`PYAPP_DISTRIBUTION_VARIANT_GIL`	Linux Windows macOS	`freethreaded`

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 defined distribution ID.

Path prefix¶

If the Python executable and the site-packages directory are at the default locations but nested under top-level directories, you may set the PYAPP_DISTRIBUTION_PATH_PREFIX option to the common prefix of the two paths to avoid having to manually set those options.

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.

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.