# pypa/pipx architecture

> Architecture diagram of the GitHub repository pypa/pipx, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pypa/pipx
- Repository: https://github.com/pypa/pipx

## Overview

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: [`src/pipx/venv.py`](https://github.com/pypa/pipx/blob/main/src/pipx/venv.py) (Virtual environments), [`src/pipx/commands/__init__.py`](https://github.com/pypa/pipx/blob/main/src/pipx/commands/__init__.py) (Command registry), [`src/pipx/commands/install.py`](https://github.com/pypa/pipx/blob/main/src/pipx/commands/install.py) (Install applications), [`src/pipx/pipx_metadata_file.py`](https://github.com/pypa/pipx/blob/main/src/pipx/pipx_metadata_file.py) (Environment metadata)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI and commands"]
  node_cli["CLI dispatch<br/>[main.py]"]
  node_command_registry["Command registry<br/>[__init__.py]"]
  node_environment_cmd["Environment settings<br/>[environment.py]"]
  node_list["List packages<br/>[list_packages.py]"]
  node_ensure_path["Ensure executable path<br/>[ensure_path.py]"]
end

subgraph group_lifecycle["Application lifecycle"]
  node_install["Install applications<br/>[install.py]"]
  node_run["Run applications<br/>[run.py]"]
  node_manage["Manage packages<br/>[upgrade.py]"]
  node_uninstall["Uninstall packages<br/>[uninstall.py]"]
  node_inject["Inject dependencies<br/>[inject.py]"]
  node_manifest["Manifest restore<br/>[manifest.py]"]
  node_common["Install validation<br/>[common.py]"]
  node_expose["Expose applications<br/>[expose.py]"]
end

subgraph group_environment["Environment execution"]
  node_interpreter["Python resolution<br/>[interpreter.py]"]
  node_venv["Virtual environments<br/>[venv.py]"]
  node_backend["Install backends<br/>[_base.py]"]
  node_pip_backend["Pip backend<br/>[pip.py]"]
  node_uv_backend["uv backend<br/>[uv.py]"]
  node_shared_libs["Shared libraries<br/>[shared_libs.py]"]
  node_standalone_python["Standalone Python"]
end

subgraph group_foundation["Shared foundations"]
  node_spec["Package parsing"]
  node_metadata[("Environment metadata")]
  node_paths["Managed paths<br/>[paths.py]"]
  node_script["Script handling<br/>[script.py]"]
  node_venv_inspect["Environment inspection<br/>[venv_inspect.py]"]
  node_result["Operation results<br/>[result.py]"]
  node_util["Process and filesystem utilities<br/>[util.py]"]
end

node_user(("User"))

node_user -->|"runs command"| node_cli
node_cli -->|"dispatches commands"| node_command_registry
node_command_registry -->|"registers"| node_install
node_command_registry -->|"registers"| node_run
node_command_registry -->|"registers"| node_manage
node_command_registry -->|"registers"| node_uninstall
node_command_registry -->|"registers"| node_inject
node_command_registry -->|"registers"| node_list
node_command_registry -->|"registers"| node_ensure_path
node_command_registry -->|"registers"| node_environment_cmd
node_install -->|"uses validation"| node_common
node_install -->|"parses package"| node_spec
node_install -->|"resolves Python"| node_interpreter
node_install -->|"creates environment"| node_venv
node_install -->|"records install"| node_metadata
node_run -->|"runs application"| node_venv
node_run -->|"handles scripts"| node_script
node_manage -->|"upgrades environments"| node_venv
node_manage -->|"reads metadata"| node_metadata
node_uninstall -->|"removes environment"| node_venv
node_uninstall -->|"reads metadata"| node_metadata
node_inject -->|"installs dependencies"| node_venv
node_inject -->|"updates metadata"| node_metadata
node_manifest -->|"loads metadata"| node_metadata
node_manifest -->|"restores installs"| node_install
node_environment_cmd -->|"reports locations"| node_paths
node_common -->|"checks environments"| node_venv
node_venv -->|"delegates operations"| node_backend
node_backend -->|"selects implementation"| node_pip_backend
node_backend -->|"selects implementation"| node_uv_backend
node_venv -->|"resolves interpreter"| node_interpreter
node_venv -->|"manages shared libraries"| node_shared_libs
node_interpreter -->|"fetches interpreter"| node_standalone_python
node_venv -->|"stores environment state"| node_metadata
node_venv -->|"inspects packages"| node_venv_inspect
node_venv -->|"installs scripts"| node_script
node_metadata -->|"uses backend metadata"| node_backend
node_paths -->|"supports filesystem operations"| node_util
node_install -->|"returns operation result"| node_result
node_list -.->|"lists environments"| node_venv
node_ensure_path -.->|"configures executable path"| node_paths
node_expose -.->|"exposes entry points"| node_venv

click node_cli "https://github.com/pypa/pipx/blob/main/src/pipx/main.py"
click node_command_registry "https://github.com/pypa/pipx/blob/main/src/pipx/commands/__init__.py"
click node_install "https://github.com/pypa/pipx/blob/main/src/pipx/commands/install.py"
click node_run "https://github.com/pypa/pipx/blob/main/src/pipx/commands/run.py"
click node_manage "https://github.com/pypa/pipx/blob/main/src/pipx/commands/upgrade.py"
click node_uninstall "https://github.com/pypa/pipx/blob/main/src/pipx/commands/uninstall.py"
click node_inject "https://github.com/pypa/pipx/blob/main/src/pipx/commands/inject.py"
click node_manifest "https://github.com/pypa/pipx/blob/main/src/pipx/commands/manifest.py"
click node_environment_cmd "https://github.com/pypa/pipx/blob/main/src/pipx/commands/environment.py"
click node_common "https://github.com/pypa/pipx/blob/main/src/pipx/commands/common.py"
click node_spec "https://github.com/pypa/pipx/blob/main/src/pipx/package_specifier.py"
click node_interpreter "https://github.com/pypa/pipx/blob/main/src/pipx/interpreter.py"
click node_venv "https://github.com/pypa/pipx/blob/main/src/pipx/venv.py"
click node_backend "https://github.com/pypa/pipx/blob/main/src/pipx/backends/_base.py"
click node_pip_backend "https://github.com/pypa/pipx/blob/main/src/pipx/backends/pip.py"
click node_uv_backend "https://github.com/pypa/pipx/blob/main/src/pipx/backends/uv.py"
click node_metadata "https://github.com/pypa/pipx/blob/main/src/pipx/pipx_metadata_file.py"
click node_paths "https://github.com/pypa/pipx/blob/main/src/pipx/paths.py"
click node_shared_libs "https://github.com/pypa/pipx/blob/main/src/pipx/shared_libs.py"
click node_standalone_python "https://github.com/pypa/pipx/blob/main/src/pipx/standalone_python.py"
click node_script "https://github.com/pypa/pipx/blob/main/src/pipx/script.py"
click node_venv_inspect "https://github.com/pypa/pipx/blob/main/src/pipx/venv_inspect.py"
click node_result "https://github.com/pypa/pipx/blob/main/src/pipx/result.py"
click node_util "https://github.com/pypa/pipx/blob/main/src/pipx/util.py"
click node_list "https://github.com/pypa/pipx/blob/main/src/pipx/commands/list_packages.py"
click node_ensure_path "https://github.com/pypa/pipx/blob/main/src/pipx/commands/ensure_path.py"
click node_expose "https://github.com/pypa/pipx/blob/main/src/pipx/commands/expose.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_command_registry,node_environment_cmd,node_list,node_ensure_path,node_user toneBlue
class node_install,node_run,node_manage,node_uninstall,node_inject,node_manifest,node_common,node_expose toneAmber
class node_interpreter,node_venv,node_backend,node_pip_backend,node_uv_backend,node_shared_libs,node_standalone_python toneMint
class node_spec,node_metadata,node_paths,node_script,node_venv_inspect,node_result,node_util toneRose
```

## Components

### CLI and commands

- [CLI dispatch](https://github.com/pypa/pipx/blob/main/src/pipx/main.py): `src/pipx/main.py`
- [Command registry](https://github.com/pypa/pipx/blob/main/src/pipx/commands/__init__.py): `src/pipx/commands/__init__.py`
- [Environment settings](https://github.com/pypa/pipx/blob/main/src/pipx/commands/environment.py): `src/pipx/commands/environment.py`
- [List packages](https://github.com/pypa/pipx/blob/main/src/pipx/commands/list_packages.py): `src/pipx/commands/list_packages.py`
- [Ensure executable path](https://github.com/pypa/pipx/blob/main/src/pipx/commands/ensure_path.py): `src/pipx/commands/ensure_path.py`

### Application lifecycle

- [Install applications](https://github.com/pypa/pipx/blob/main/src/pipx/commands/install.py): `src/pipx/commands/install.py`
- [Run applications](https://github.com/pypa/pipx/blob/main/src/pipx/commands/run.py): `src/pipx/commands/run.py`
- [Manage packages](https://github.com/pypa/pipx/blob/main/src/pipx/commands/upgrade.py): `src/pipx/commands/upgrade.py`
- [Uninstall packages](https://github.com/pypa/pipx/blob/main/src/pipx/commands/uninstall.py): `src/pipx/commands/uninstall.py`
- [Inject dependencies](https://github.com/pypa/pipx/blob/main/src/pipx/commands/inject.py): `src/pipx/commands/inject.py`
- [Manifest restore](https://github.com/pypa/pipx/blob/main/src/pipx/commands/manifest.py): `src/pipx/commands/manifest.py`
- [Install validation](https://github.com/pypa/pipx/blob/main/src/pipx/commands/common.py): `src/pipx/commands/common.py`
- [Expose applications](https://github.com/pypa/pipx/blob/main/src/pipx/commands/expose.py): `src/pipx/commands/expose.py`

### Environment execution

- [Python resolution](https://github.com/pypa/pipx/blob/main/src/pipx/interpreter.py): `src/pipx/interpreter.py`
- [Virtual environments](https://github.com/pypa/pipx/blob/main/src/pipx/venv.py): `src/pipx/venv.py`
- [Install backends](https://github.com/pypa/pipx/blob/main/src/pipx/backends/_base.py): `src/pipx/backends/_base.py`
- [Pip backend](https://github.com/pypa/pipx/blob/main/src/pipx/backends/pip.py): `src/pipx/backends/pip.py`
- [uv backend](https://github.com/pypa/pipx/blob/main/src/pipx/backends/uv.py): `src/pipx/backends/uv.py`
- [Shared libraries](https://github.com/pypa/pipx/blob/main/src/pipx/shared_libs.py): `src/pipx/shared_libs.py`
- [Standalone Python](https://github.com/pypa/pipx/blob/main/src/pipx/standalone_python.py): `src/pipx/standalone_python.py`

### Shared foundations

- [Package parsing](https://github.com/pypa/pipx/blob/main/src/pipx/package_specifier.py): `src/pipx/package_specifier.py`
- [Environment metadata](https://github.com/pypa/pipx/blob/main/src/pipx/pipx_metadata_file.py): `src/pipx/pipx_metadata_file.py`
- [Managed paths](https://github.com/pypa/pipx/blob/main/src/pipx/paths.py): `src/pipx/paths.py`
- [Script handling](https://github.com/pypa/pipx/blob/main/src/pipx/script.py): `src/pipx/script.py`
- [Environment inspection](https://github.com/pypa/pipx/blob/main/src/pipx/venv_inspect.py): `src/pipx/venv_inspect.py`
- [Operation results](https://github.com/pypa/pipx/blob/main/src/pipx/result.py): `src/pipx/result.py`
- [Process and filesystem utilities](https://github.com/pypa/pipx/blob/main/src/pipx/util.py): `src/pipx/util.py`

### Other components

- **User**

## Connections

- User → CLI dispatch: runs command
- CLI dispatch → Command registry: dispatches commands (evidence: `src/pipx/main.py`)
- Command registry → Install applications: registers (evidence: `src/pipx/commands/__init__.py`)
- Command registry → Run applications: registers (evidence: `src/pipx/commands/__init__.py`)
- Command registry → Manage packages: registers (evidence: `src/pipx/commands/__init__.py`)
- Command registry → Uninstall packages: registers (evidence: `src/pipx/commands/__init__.py`)
- Command registry → Inject dependencies: registers (evidence: `src/pipx/commands/__init__.py`)
- Command registry → List packages: registers (evidence: `src/pipx/commands/__init__.py`)
- Command registry → Ensure executable path: registers (evidence: `src/pipx/commands/__init__.py`)
- Command registry → Environment settings: registers (evidence: `src/pipx/commands/__init__.py`)
- Install applications → Install validation: uses validation (evidence: `src/pipx/commands/install.py`)
- Install applications → Package parsing: parses package (evidence: `src/pipx/commands/install.py`)
- Install applications → Python resolution: resolves Python (evidence: `src/pipx/commands/install.py`)
- Install applications → Virtual environments: creates environment (evidence: `src/pipx/commands/install.py`)
- Install applications → Environment metadata: records install (evidence: `src/pipx/commands/install.py`)
- Run applications → Virtual environments: runs application (evidence: `src/pipx/commands/run.py`)
- Run applications → Script handling: handles scripts (evidence: `src/pipx/commands/run.py`)
- Manage packages → Virtual environments: upgrades environments (evidence: `src/pipx/commands/upgrade.py`)
- Manage packages → Environment metadata: reads metadata (evidence: `src/pipx/commands/upgrade.py`)
- Uninstall packages → Virtual environments: removes environment (evidence: `src/pipx/commands/uninstall.py`)
- Uninstall packages → Environment metadata: reads metadata (evidence: `src/pipx/commands/uninstall.py`)
- Inject dependencies → Virtual environments: installs dependencies (evidence: `src/pipx/commands/inject.py`)
- Inject dependencies → Environment metadata: updates metadata (evidence: `src/pipx/commands/inject.py`)
- Manifest restore → Environment metadata: loads metadata (evidence: `src/pipx/commands/manifest.py`)
- Manifest restore → Install applications: restores installs (evidence: `src/pipx/commands/manifest.py`)
- Environment settings → Managed paths: reports locations (evidence: `src/pipx/commands/environment.py`)
- Install validation → Virtual environments: checks environments (evidence: `src/pipx/commands/common.py`)
- Virtual environments → Install backends: delegates operations (evidence: `src/pipx/venv.py`)
- Install backends → Pip backend: selects implementation (evidence: `src/pipx/backends/__init__.py`)
- Install backends → uv backend: selects implementation (evidence: `src/pipx/backends/__init__.py`)
- Virtual environments → Python resolution: resolves interpreter (evidence: `src/pipx/venv.py`)
- Virtual environments → Shared libraries: manages shared libraries (evidence: `src/pipx/venv.py`)
- Python resolution → Standalone Python: fetches interpreter (evidence: `src/pipx/interpreter.py`)
- Virtual environments → Environment metadata: stores environment state (evidence: `src/pipx/venv.py`)
- Virtual environments → Environment inspection: inspects packages (evidence: `src/pipx/venv.py`)
- Virtual environments → Script handling: installs scripts (evidence: `src/pipx/venv.py`)
- Environment metadata → Install backends: uses backend metadata (evidence: `src/pipx/pipx_metadata_file.py`)
- Managed paths → Process and filesystem utilities: supports filesystem operations (evidence: `src/pipx/util.py`)
- Install applications → Operation results: returns operation result (evidence: `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
