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:

[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:

[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 resolves each locked dependency group into a PEP 751 lock file. Install it, then generate the declared locks:

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

pipx manifest lock passes the manifest to nab once per locked dependency group. Existing locks seed their replacements, and pipx overwrites the declared files only after every resolution succeeds. Entries without lock stay unlocked.

Apply the manifest

$ 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:

$ 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

$ pipx list --short

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