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)