How pypa/pipx works
pipx installs and runs Python command-line applications in isolated virtual environments. The principal workflow is a user command entering the CLI, resolving a package specification and Python interpreter, creating or reusing an environment, installing the application, and exposing its entry points. Management commands also support injection, upgrades, listing, uninstalling, and environment configuration; run provides temporary application environments. The graph reflects the README and SOURCE INDEX references; unsampled command implementations are represented by their exact tree paths, without inferring undocumented call details.
Main entry points: venv.py Virtual environments · __init__.py Command registry · install.py Install applications · pipx_metadata_file.py Environment metadata
Components 28
CLI and commands
- CLI dispatch
src/pipx/main.py - Command registry
src/pipx/commands/__init__.py - Environment settings
src/pipx/commands/environment.py - List packages
src/pipx/commands/list_packages.py - Ensure executable path
src/pipx/commands/ensure_path.py
Application lifecycle
- Install applications
src/pipx/commands/install.py - Run applications
src/pipx/commands/run.py - Manage packages
src/pipx/commands/upgrade.py - Uninstall packages
src/pipx/commands/uninstall.py - Inject dependencies
src/pipx/commands/inject.py - Manifest restore
src/pipx/commands/manifest.py - Install validation
src/pipx/commands/common.py - Expose applications
src/pipx/commands/expose.py
Environment execution
- Python resolution
src/pipx/interpreter.py - Virtual environments
src/pipx/venv.py - Install backends
src/pipx/backends/_base.py - Pip backend
src/pipx/backends/pip.py - uv backend
src/pipx/backends/uv.py - Shared libraries
src/pipx/shared_libs.py - Standalone Python
src/pipx/standalone_python.py
Shared foundations
- Package parsing
src/pipx/package_specifier.py - Environment metadata
src/pipx/pipx_metadata_file.py - Managed paths
src/pipx/paths.py - Script handling
src/pipx/script.py - Environment inspection
src/pipx/venv_inspect.py - Operation results
src/pipx/result.py - Process and filesystem utilities
src/pipx/util.py
Other components
- User
Connections 42
- User → CLI dispatch: runs command
- CLI dispatch → Command registry: dispatches commands
src/pipx/main.py - Command registry → Install applications: registers
src/pipx/commands/__init__.py - Command registry → Run applications: registers
src/pipx/commands/__init__.py - Command registry → Manage packages: registers
src/pipx/commands/__init__.py - Command registry → Uninstall packages: registers
src/pipx/commands/__init__.py - Command registry → Inject dependencies: registers
src/pipx/commands/__init__.py - Command registry → List packages: registers
src/pipx/commands/__init__.py - Command registry → Ensure executable path: registers
src/pipx/commands/__init__.py - Command registry → Environment settings: registers
src/pipx/commands/__init__.py - Install applications → Install validation: uses validation
src/pipx/commands/install.py - Install applications → Package parsing: parses package
src/pipx/commands/install.py - Install applications → Python resolution: resolves Python
src/pipx/commands/install.py - Install applications → Virtual environments: creates environment
src/pipx/commands/install.py - Install applications → Environment metadata: records install
src/pipx/commands/install.py - Run applications → Virtual environments: runs application
src/pipx/commands/run.py - Run applications → Script handling: handles scripts
src/pipx/commands/run.py - Manage packages → Virtual environments: upgrades environments
src/pipx/commands/upgrade.py - Manage packages → Environment metadata: reads metadata
src/pipx/commands/upgrade.py - Uninstall packages → Virtual environments: removes environment
src/pipx/commands/uninstall.py - Uninstall packages → Environment metadata: reads metadata
src/pipx/commands/uninstall.py - Inject dependencies → Virtual environments: installs dependencies
src/pipx/commands/inject.py - Inject dependencies → Environment metadata: updates metadata
src/pipx/commands/inject.py - Manifest restore → Environment metadata: loads metadata
src/pipx/commands/manifest.py - Manifest restore → Install applications: restores installs
src/pipx/commands/manifest.py - Environment settings → Managed paths: reports locations
src/pipx/commands/environment.py - Install validation → Virtual environments: checks environments
src/pipx/commands/common.py - Virtual environments → Install backends: delegates operations
src/pipx/venv.py - Install backends → Pip backend: selects implementation
src/pipx/backends/__init__.py - Install backends → uv backend: selects implementation
src/pipx/backends/__init__.py - Virtual environments → Python resolution: resolves interpreter
src/pipx/venv.py - Virtual environments → Shared libraries: manages shared libraries
src/pipx/venv.py - Python resolution → Standalone Python: fetches interpreter
src/pipx/interpreter.py - Virtual environments → Environment metadata: stores environment state
src/pipx/venv.py - Virtual environments → Environment inspection: inspects packages
src/pipx/venv.py - Virtual environments → Script handling: installs scripts
src/pipx/venv.py - Environment metadata → Install backends: uses backend metadata
src/pipx/pipx_metadata_file.py - Managed paths → Process and filesystem utilities: supports filesystem operations
src/pipx/util.py - Install applications → Operation results: returns operation result
src/pipx/commands/install.py - List packages → Virtual environments: lists environments
- Ensure executable path → Managed paths: configures executable path
- Expose applications → Virtual environments: exposes entry points