###############
 Project scope
###############

pipx installs and runs Python applications. It manages the isolated environments that support those applications and
exposes their entry points on ``PATH``.

*******************
 What pipx manages
*******************

-  Persistent application environments for ``pipx install`` and disposable environments for ``pipx run``.
-  User installations by default and system installations when the caller passes ``--global``.
-  Application dependencies inside a managed environment. For unlocked environments, ``inject`` and ``--preinstall``
   extend an application environment; they do not create standalone library environments.
-  Entry points from the main package and dependencies named with ``--include-resources-from`` or ``--include-deps``.

An install fails when neither the package nor its selected dependencies expose an application. The caller can pass
``--app NAME`` to require an exact entry point. pipx removes a new environment or restores an existing one when the check
fails.

************
 Boundaries
************

pipx does not manage these use cases:

-  standalone environments for importing libraries or modules;
-  tool selection based on the current directory, parent directories, or project metadata;
-  system installation inferred from elevated privileges;
-  a ``pip`` executable from each managed environment on ``PATH``;
-  package search, package ranking, or index-specific application discovery; or
-  frozen pipx executables, operating-system packages, zipapp installers, repositories, and signing keys.

Use ``pipx runpip`` when you need package-manager access inside an environment that pipx created. Distribution projects
may package pipx for their users, but each ecosystem owns its build, release, update, and signing process.

**************************
 Configuration and state
**************************

Ordinary pipx commands do not search the current directory or its parents for configuration. ``pipx manifest sync
PATH`` applies the desired application state from the manifest at ``PATH``; pipx does not infer that path. The manifest
accepts tool state instead of arbitrary command defaults.

pipx can record an environment's resolved dependencies as a lock file in the PyPA ``pylock.toml`` format, so the
environment rebuilds identically; ``pipx manifest lock`` writes these locks and ``pipx install --lock`` reads one back.
pipx does not use ``requirements.txt`` as a state or lock format.

pipx exposes top-level policy when pip and uv honor the same contract. Backend arguments carry controls specific to pip
or uv. ``--cooldown DAYS`` maps one pipx release-age policy to both backends.

Application launchers start the installed application without downloading packages or changing its environment. Health
checks and repairs belong in commands that the user invokes for those purposes.

**************************
 Existing directory lookup
**************************

``pipx run`` has experimental support for applications under ``__pypackages__/<major>.<minor>/lib/bin`` in the current
directory. This behavior predates the scope above and conflicts with the directory-discovery boundary. New features must
not use it as a model; the project should deprecate and remove it in a separate change.

********************
 Choose another tool
********************

Use a project dependency manager such as uv or Poetry for project libraries and development tools. Use ``venv``, pip, or
uv for a library environment. Use a version manager such as mise when a directory must select tool versions, and use the
system package manager to find or install operating-system packages.