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, from --cooldown or PIPX_COOLDOWN, 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).