0
# pipdeptree
1
2
A command-line utility for displaying installed Python packages in a hierarchical dependency tree format. Unlike `pip freeze` which shows packages as a flat list, pipdeptree visualizes package relationships, identifies conflicting dependencies, supports reverse dependency lookups, and provides multiple output formats including text, JSON, and GraphViz.
3
4
## Package Information
5
6
- **Package Name**: pipdeptree
7
- **Language**: Python
8
- **Installation**: `pip install pipdeptree`
9
- **Python Version**: >=3.9
10
11
## Core Imports
12
13
```python
14
# CLI entry point
15
from pipdeptree.__main__ import main
16
17
# Core model classes
18
from pipdeptree._models import DistPackage, ReqPackage, PackageDAG
19
20
# Discovery functions
21
from pipdeptree._discovery import get_installed_distributions
22
23
# CLI options
24
from pipdeptree._cli import get_options, Options
25
26
# Validation
27
from pipdeptree._validate import validate
28
29
# Rendering
30
from pipdeptree._render import render
31
32
# Freeze utilities
33
from pipdeptree._freeze import dist_to_frozen_repr
34
```
35
36
## Basic Usage
37
38
### Command Line Interface
39
40
```bash
41
# Show dependency tree for all packages
42
pipdeptree
43
44
# Show specific packages only
45
pipdeptree --packages django,requests
46
47
# Show reverse dependencies (what depends on a package)
48
pipdeptree --reverse --packages numpy
49
50
# Output as JSON
51
pipdeptree --json
52
53
# Output as nested JSON tree
54
pipdeptree --json-tree
55
56
# Use custom Python interpreter
57
pipdeptree --python /path/to/python
58
59
# Auto-detect virtual environment
60
pipdeptree --python auto
61
```
62
63
### Programmatic Usage
64
65
```python
66
from pipdeptree._discovery import get_installed_distributions
67
from pipdeptree._models import PackageDAG
68
from pipdeptree._validate import validate
69
from pipdeptree._render import render
70
from pipdeptree._cli import get_options
71
72
# Get installed packages
73
distributions = get_installed_distributions()
74
75
# Create dependency tree
76
tree = PackageDAG.from_pkgs(distributions)
77
78
# Validate for conflicts and cycles
79
validate(tree)
80
81
# Parse CLI options and render
82
options = get_options(['--json'])
83
render(options, tree)
84
```
85
86
## Architecture
87
88
pipdeptree uses a directed acyclic graph (DAG) structure to represent package dependencies:
89
90
- **PackageDAG**: Main container mapping packages to their requirements
91
- **DistPackage**: Represents installed distribution packages with metadata
92
- **ReqPackage**: Represents package requirements with version constraints
93
- **Discovery**: Queries Python environments for installed packages
94
- **Validation**: Detects conflicting and circular dependencies
95
- **Rendering**: Outputs trees in various formats (text, JSON, GraphViz, Mermaid)
96
97
## Capabilities
98
99
### Package Discovery
100
101
Discovers and queries installed Python packages across different environments, interpreters, and installation scopes.
102
103
```python { .api }
104
def get_installed_distributions(
105
interpreter: str = sys.executable or "",
106
supplied_paths: list[str] | None = None,
107
local_only: bool = False,
108
user_only: bool = False,
109
) -> list[Distribution]: ...
110
```
111
112
[Package Discovery](./package-discovery.md)
113
114
### Data Models
115
116
Core classes for representing packages, requirements, and dependency relationships in a hierarchical structure.
117
118
```python { .api }
119
class DistPackage:
120
def __init__(self, obj: Distribution, req: ReqPackage | None = None): ...
121
def requires(self) -> Iterator[Requirement]: ...
122
@property
123
def version(self) -> str: ...
124
125
class ReqPackage:
126
def __init__(self, obj: Requirement, dist: DistPackage | None = None): ...
127
@property
128
def version_spec(self) -> str | None: ...
129
def is_conflicting(self) -> bool: ...
130
131
class PackageDAG(Mapping[DistPackage, list[ReqPackage]]):
132
@classmethod
133
def from_pkgs(cls, pkgs: list[Distribution]) -> PackageDAG: ...
134
def filter_nodes(self, include, exclude, exclude_deps=False): ...
135
def reverse(self) -> ReversedPackageDAG: ...
136
```
137
138
[Data Models](./data-models.md)
139
140
### Dependency Validation
141
142
Validates dependency trees to identify conflicting versions and circular dependencies with detailed reporting.
143
144
```python { .api }
145
def validate(tree: PackageDAG) -> None: ...
146
def conflicting_deps(tree: PackageDAG) -> dict[DistPackage, list[ReqPackage]]: ...
147
def cyclic_deps(tree: PackageDAG) -> list[list[Package]]: ...
148
```
149
150
[Dependency Validation](./validation.md)
151
152
### CLI Interface
153
154
Command-line argument parsing and option handling with comprehensive configuration support.
155
156
```python { .api }
157
class Options(Namespace):
158
freeze: bool
159
python: str
160
packages: str
161
exclude: str
162
reverse: bool
163
json: bool
164
json_tree: bool
165
output_format: str | None
166
# ... additional options
167
168
def get_options(args: Sequence[str] | None) -> Options: ...
169
def main(args: Sequence[str] | None = None) -> int | None: ...
170
```
171
172
[CLI Interface](./cli-interface.md)
173
174
### Output Rendering
175
176
Renders dependency trees in multiple formats including text, JSON, GraphViz, Mermaid, and freeze formats.
177
178
```python { .api }
179
def render(options: Options, tree: PackageDAG) -> None: ...
180
```
181
182
[Output Rendering](./output-rendering.md)
183
184
### Environment Detection
185
186
Automatically detects and configures for virtual environments including venv, virtualenv, conda, and Poetry.
187
188
```python { .api }
189
def detect_active_interpreter() -> str: ...
190
```
191
192
[Environment Detection](./environment-detection.md)
193
194
### Warning System
195
196
Configurable warning and error reporting system with different verbosity levels and output control.
197
198
```python { .api }
199
class WarningType(Enum):
200
SILENCE = "silence"
201
SUPPRESS = "suppress"
202
FAIL = "fail"
203
204
class WarningPrinter:
205
def __init__(self, warning_type: WarningType = WarningType.SUPPRESS): ...
206
def should_warn(self) -> bool: ...
207
def print_single_line(self, line: str) -> None: ...
208
```
209
210
[Warning System](./warning-system.md)