0
# Package Discovery
1

2
The package discovery system provides functionality to find and query installed Python packages across different environments, interpreters, and installation scopes.
3

4
## Capabilities
5

6
### Package Discovery Function
7

8
The main entry point for discovering installed Python packages in various environments.
9

10
```python { .api }
11
def get_installed_distributions(
12
    interpreter: str = sys.executable or "",
13
    supplied_paths: list[str] | None = None,
14
    local_only: bool = False,
15
    user_only: bool = False,
16
) -> list[Distribution]:
17
    """
18
    Return the distributions installed in the interpreter's environment.
19
    
20
    Parameters:
21
    - interpreter: Python interpreter to inspect (default: current executable)
22
    - supplied_paths: Custom paths to restrict package search locations
23
    - local_only: Only show packages in virtual environment (if in venv)
24
    - user_only: Only show packages in user site directory
25
    
26
    Returns:
27
    List of importlib.metadata.Distribution objects
28
    
29
    Raises:
30
    InterpreterQueryError: If failure occurred while querying interpreter
31
    """
32
```
33

34
### Usage Examples
35

36
```python
37
import sys
38
from pipdeptree._discovery import get_installed_distributions
39

40
# Get all packages from current interpreter
41
packages = get_installed_distributions()
42

43
# Get packages from specific interpreter
44
packages = get_installed_distributions(interpreter="/path/to/python")
45

46
# Get only local virtualenv packages
47
packages = get_installed_distributions(local_only=True)
48

49
# Get only user-installed packages
50
packages = get_installed_distributions(user_only=True)
51

52
# Use custom paths to restrict search
53
packages = get_installed_distributions(
54
    supplied_paths=["/custom/site-packages"]
55
)
56
```
57

58
### Environment Detection
59

60
Automatic detection of virtual environments including venv, virtualenv, conda, and Poetry.
61

62
```python { .api }
63
def detect_active_interpreter() -> str:
64
    """
65
    Attempt to detect a venv, virtualenv, poetry, or conda environment.
66
    
67
    Returns:
68
    Path to the detected interpreter
69
    
70
    Raises:
71
    SystemExit: If unable to detect virtual environment
72
    """
73
```
74

75
Detection methods include:
76
- **venv/virtualenv**: Uses `VIRTUAL_ENV` environment variable
77
- **conda**: Uses `CONDA_PREFIX` environment variable  
78
- **Poetry**: Executes `poetry env info --executable`
79

80
```python
81
from pipdeptree._detect_env import detect_active_interpreter
82

83
# Auto-detect current virtual environment
84
interpreter_path = detect_active_interpreter()
85
packages = get_installed_distributions(interpreter=interpreter_path)
86
```
87

88
### Internal Discovery Functions
89

90
Additional internal functions for path resolution and filtering:
91

92
```python { .api }
93
def query_interpreter_for_paths(
94
    interpreter: str, 
95
    local_only: bool = False
96
) -> list[str]: ...
97

98
def filter_valid_distributions(
99
    distributions: Iterable[Distribution]
100
) -> list[Distribution]: ...
101
```
102

103
## Exceptions
104

105
```python { .api }
106
class InterpreterQueryError(Exception):
107
    """A problem occurred while trying to query a custom interpreter."""
108
```
109

110
## Environment Variables
111

112
The discovery system respects several environment variables:
113

114
- **VIRTUAL_ENV**: Path to virtual environment (venv/virtualenv)
115
- **CONDA_PREFIX**: Path to conda environment
116
- **PYTHONPATH**: Additional module search paths
117

118
## Path Resolution
119

120
The system handles various installation locations:
121

122
- **Global site-packages**: System-wide Python installations
123
- **Virtual environments**: Isolated package environments
124
- **User site directory**: User-specific package installations (`--user`)
125
- **Custom paths**: Explicitly provided search locations