##############
 Tool manifest
##############

Declare a set of pipx tools in one file and install, upgrade, or prune them as a unit with ``pipx manifest``.

*******************
 Write the manifest
*******************

The manifest is a ``pipx.toml`` file. Each dependency group holds one PEP 508 package requirement and names its pipx
environment. Keep ``project.dependencies`` empty so each group resolves on its own:

.. code-block:: toml

    [project]
    name = "pipx-tools"
    version = "1"
    dependencies = []
    requires-python = ">=3.10"

    [dependency-groups]
    black = ["black>=25,<26"]
    httpie = ["httpie"]

    [tool.pipx]
    version = "1.0"

    [tool.pipx.tools.black]
    apps = ["black"]
    lock = "pylock.black.toml"

    [tool.pipx.tools.httpie]
    apps = ["http", "https"]

Add a ``tool.pipx.tools`` table only when a tool needs policy beyond its package requirement. A tool table may set
``suffix``, ``apps``, ``include-dependencies``, ``include-resources-from``, ``expose``, or ``lock``. Use
``include-resources-from = ["PACKAGE"]`` to select dependency resources; do not combine it with
``include-dependencies``. Relative ``lock`` paths start from the manifest directory. Put nab settings in ``tool.nab``.

Use the normalized package name plus its suffix as the environment name when a tool sets a suffix:

.. code-block:: toml

    [dependency-groups]
    black-24 = ["black==24.10.0"]

    [tool.pipx.tools.black-24]
    suffix = "-24"
    apps = ["black"]

Package requirements use PEP 508 syntax without environment markers.

******************
 Lock the manifest
******************

`nab <https://pypi.org/project/nab/>`_ resolves each locked dependency group into a PEP 751 lock file. Install it, then
generate the declared locks:

.. code-block:: console

    $ pipx install nab
    $ pipx manifest lock ./pipx.toml

``pipx manifest lock`` passes the manifest to nab once per locked dependency group, and records that group as the
lock's default so installers select it. Existing locks seed their replacements, and pipx overwrites the declared files
only after every resolution succeeds. Entries without ``lock`` stay unlocked.

*******************
 Apply the manifest
*******************

.. code-block:: console

    $ pipx manifest sync ./pipx.toml

``sync`` installs, upgrades, or downgrades each declared tool. The backend resolves unlocked specs on each run; locked
entries install from the artifacts in their named PEP 751 files. pipx restores an existing environment and its exposed
resources when a tool fails to install or lacks a required app.

Pass ``--prune`` to uninstall environments absent from the manifest:

.. code-block:: console

    $ pipx manifest sync ./pipx.toml --prune

Without ``--prune``, sync leaves your other pipx environments alone. Pass ``--global`` or ``--backend`` after ``sync``
to select the pipx store or the installation backend. pipx reads only the manifest path you supply on the command line.

**********
 Verify it
**********

.. code-block:: console

    $ pipx list --short

Each declared tool appears at the version its group resolved to.