On-disk metadata

pipx has no user configuration file. It is configured only through environment variables. The only per-installation state pipx keeps is a metadata file inside each managed virtual environment.

Every environment under $PIPX_HOME/venvs/<environment>/ holds a pipx_metadata.json file. pipx writes it after each operation and reads it to drive list, upgrade, reinstall, uninstall, and the rest. Treat it as pipx-owned; pipx rewrites it atomically and may change its shape between versions.

The current schema version is 0.12 (pipx_metadata_version). pipx migrates older files forward on read.

Top-level fields

Field	Meaning
pipx_metadata_version	Schema version string, currently "0.12".
environment	The environment (venv) name, or null.
main_package	Package record for the installed application (see below).
injected_packages	Map of injected package name to its package record.
python_version	Python version the environment was created with, or null.
source_interpreter	Path to the interpreter used to create the environment, or null.
venv_args	Extra arguments passed when the venv was created (for example --system-site-packages).
backend	Backend that manages the environment, pip or uv. An unknown value is read back as pip with a warning.
exposure_enabled	Whether the environment’s apps and man pages are currently exposed on PATH.

Package records

main_package and each entry in injected_packages share this shape:

Field	Meaning
package	Canonical package name, or null.
package_or_url	The install source as given: a package name, path, or URL.
package_version	Resolved installed version.
pip_args	Arguments forwarded to the backend at install time.
include_dependencies	Whether apps and man pages from all dependencies are exposed.
include_resources_from	Dependencies whose apps and man pages are exposed individually.
include_apps	Whether this package’s own apps are exposed. Always true for main_package.
apps / app_paths	App names and their paths inside the environment.
apps_of_dependencies / app_paths_of_dependencies	Apps contributed by dependencies, and their paths keyed by dependency.
man_pages / man_paths	Man page names and their paths inside the environment.
man_pages_of_dependencies / man_paths_of_dependencies	Man pages contributed by dependencies, and their paths keyed by dependency.
completions / completion_paths	Shell completion names and their paths inside the environment.
completions_of_dependencies / completion_paths_of_dependencies	Completions contributed by dependencies, and their paths keyed by dependency.
expected_apps	Apps required after install via --app.
lock_file	Path to the pylock.toml used to install, or null.
cooldown_days	Index-artifact cooldown recorded for the install, or null.
suffix	Suffix appended to the environment and executable names, or empty.
pinned	Whether the package is pinned against upgrades.

Note

Path values are encoded as {"__type__": "Path", "__Path__": "<path>"} so pipx can round-trip them across platforms. The same snapshot, wrapped under pipx_spec_version and a venvs map, is what pipx list --output json emits and pipx install-all consumes (see JSON output).