Runtime behavior¶

Initialization¶

Applications will bootstrap themselves on the first run. All subsequent invocations will only check if the installation directory exists and nothing else, to maximize CLI responsiveness.

Note

The following diagram shows the possible behavior at runtime. The nodes with rounded edges are conditions and those with jagged edges are actions.

Most nodes are clickable and will take you to the relevant documentation.

Execution¶

Projects are executed using execvp on non-Windows systems, replacing the process.

To provide consistent behavior on each user's machine:

Python runs projects in isolated mode
When installing or upgrading projects, pip uses isolation (by default)

Detection¶

A single environment variable called PYAPP is injected with the value of 1 (by default) when running applications and may be used to detect this mode of installation versus others.

Commands¶

Built applications have a single top-level command group named self (by default) and all other invocations will be forwarded to your actual execution logic.

Default¶

These commands are always exposed.

Remove¶

<EXE> self remove

This will wipe the installation.

Restore¶

<EXE> self restore

This will wipe the installation and then reinstall.

Update¶

<EXE> self update

This will update the project to the latest available version in the currently used distribution.

Optional¶

These commands are hidden by default and each can be individually exposed by setting its corresponding PYAPP_EXPOSE_<COMMAND> option (e.g. PYAPP_EXPOSE_METADATA) to true or 1.

You can enable all of them at once by setting the PYAPP_EXPOSE_ALL_COMMANDS option to true or 1. Individual commands that are explicitly disabled (PYAPP_EXPOSE_<COMMAND> set to false or 0) will not be exposed.

Cache¶

<EXE> self cache [dist|pip|uv]

This is the command group for managing the cache. Each subcommand has a -r/--remove flag to remove the cached asset. Not passing that flag will display the location instead.

Metadata¶

<EXE> self metadata

This displays customized output based on a template.

pip¶

<EXE> self pip

This directly invokes pip with the installed Python.

Python¶

<EXE> self python

This directly invokes the installed Python.

Python path¶

<EXE> self python-path

This outputs the path to the installed Python.