0
# Pip
1
2
The PyPA recommended tool for installing Python packages. Pip is the standard package manager for Python that installs packages from the Python Package Index (PyPI) and other repositories. It provides comprehensive package management capabilities including installation, uninstallation, dependency resolution, and package information queries.
3
4
**IMPORTANT**: Pip is designed as a command-line tool only and explicitly provides no public Python API for programmatic use. All functionality must be accessed through the CLI interface or subprocess calls.
5
6
## Package Information
7
8
- **Package Name**: pip
9
- **Package Type**: Command-line tool
10
- **Language**: Python
11
- **Installation**: Comes pre-installed with Python 3.4+ and Python 2.7.9+
12
- **Entry Points**: `pip`, `pip3`, `python -m pip`
13
14
## Core Usage
15
16
### Command Invocation
17
18
```bash { .api }
19
# Direct command usage
20
pip [command] [options]
21
pip3 [command] [options]
22
23
# Module execution
24
python -m pip [command] [options]
25
```
26
27
### Programmatic Usage (Recommended)
28
29
Since pip provides no public Python API, use subprocess for programmatic package management:
30
31
```python
32
import subprocess
33
import sys
34
35
# Install a package
36
subprocess.check_call([sys.executable, '-m', 'pip', 'install', 'requests'])
37
38
# Uninstall a package
39
subprocess.check_call([sys.executable, '-m', 'pip', 'uninstall', 'requests', '-y'])
40
41
# List installed packages
42
result = subprocess.run([sys.executable, '-m', 'pip', 'list'],
43
capture_output=True, text=True)
44
print(result.stdout)
45
```
46
47
## Basic Usage
48
49
```bash { .api }
50
# Install packages
51
pip install package_name
52
pip install package_name==1.2.3
53
pip install -r requirements.txt
54
pip install git+https://github.com/user/repo.git
55
56
# Uninstall packages
57
pip uninstall package_name
58
pip uninstall -r requirements.txt
59
60
# List installed packages
61
pip list
62
pip list --outdated
63
64
# Show package information
65
pip show package_name
66
67
# Generate requirements file
68
pip freeze > requirements.txt
69
70
# Upgrade packages
71
pip install --upgrade package_name
72
pip install --upgrade-strategy eager -r requirements.txt
73
```
74
75
## Architecture
76
77
Pip follows a command-based architecture where each operation is handled by a specific command class:
78
79
- **CLI Layer**: Command-line interface parsing and main entry point
80
- **Command Layer**: Individual command implementations (install, uninstall, list, etc.)
81
- **Resolution Layer**: Dependency resolution and conflict handling
82
- **Network Layer**: Package downloading and repository interaction
83
- **Cache Layer**: Wheel cache management and optimization
84
- **VCS Layer**: Version control system integration (git, svn, etc.)
85
86
All implementation details are contained within the `pip._internal.*` namespace and are explicitly marked as private APIs subject to change without notice.
87
88
## Capabilities
89
90
### Package Installation
91
92
Install Python packages from PyPI, version control systems, local files, and other sources with comprehensive dependency resolution and conflict handling.
93
94
```bash { .api }
95
# Basic installation
96
pip install package_name
97
98
# Install specific version
99
pip install package_name==1.2.3
100
101
# Install from requirements file
102
pip install -r requirements.txt
103
104
# Install from git repository
105
pip install git+https://github.com/user/repo.git
106
107
# Install in development mode
108
pip install -e .
109
```
110
111
[Package Installation](./installation.md)
112
113
### Package Management
114
115
Uninstall packages, list installed packages, show package information, and manage package metadata with comprehensive querying capabilities.
116
117
```bash { .api }
118
# Uninstall packages
119
pip uninstall package_name
120
121
# List packages
122
pip list
123
pip list --outdated
124
125
# Show package details
126
pip show package_name
127
128
# Check for dependency conflicts
129
pip check
130
```
131
132
[Package Management](./management.md)
133
134
### Package Building and Distribution
135
136
Build wheels, compute package hashes, and manage distribution formats for package development and deployment workflows.
137
138
```bash { .api }
139
# Build wheels
140
pip wheel .
141
pip wheel -r requirements.txt
142
143
# Compute package hashes
144
pip hash package.tar.gz
145
146
# Download without installing
147
pip download package_name
148
```
149
150
[Package Building](./building.md)
151
152
### Configuration and Environment
153
154
Manage pip configuration, inspect Python environment information, handle caching, and configure package indexes for customized package management workflows.
155
156
```bash { .api }
157
# Configuration management
158
pip config list
159
pip config set global.index-url https://pypi.org/simple/
160
161
# Environment inspection
162
pip inspect
163
164
# Cache management
165
pip cache info
166
pip cache purge
167
168
# Index operations
169
pip index versions package_name
170
171
# Help and completion
172
pip help
173
pip completion --bash
174
```
175
176
[Configuration](./configuration.md)
177
178
## API Policy
179
180
**Pip explicitly provides no public Python API.** From the official documentation:
181
182
> "pip is a command line program. While it is implemented in Python, and so is available from your Python code via import pip, you must not use pip's internal APIs in this way."
183
184
Key points:
185
- All internal APIs can change at any time without notice
186
- Pip assumes sole control of global program state
187
- Issues from unsupported programmatic usage generally won't be fixed
188
- Even the import name `pip` is subject to change
189
190
### Semi-Public Elements (Import at Your Own Risk)
191
192
```python { .api }
193
# Version information (most stable import)
194
import pip
195
print(pip.__version__) # "24.3.1"
196
197
# Deprecated main function (internal use only)
198
from pip import main # DO NOT USE - for console scripts only
199
```
200
201
## Alternative Libraries
202
203
For programmatic package management needs, consider these alternatives:
204
205
- **subprocess**: Official recommendation for calling pip programmatically
206
- **pip-tools**: Dependency resolution and requirements management
207
- **importlib.metadata**: Package metadata access (Python 3.8+)
208
- **pkg_resources**: Legacy package metadata (deprecated)
209
- **packaging**: Version parsing and specifier handling
210
- **distlib**: Low-level distribution utilities
211
212
## Error Handling
213
214
Pip exits with non-zero status codes on errors:
215
216
```python
217
import subprocess
218
import sys
219
220
try:
221
subprocess.check_call([sys.executable, '-m', 'pip', 'install', 'nonexistent-package'])
222
except subprocess.CalledProcessError as e:
223
print(f"Pip command failed with exit code {e.returncode}")
224
print(f"Command: {' '.join(e.cmd)}")
225
```
226
227
Common exit codes:
228
- `0`: Success
229
- `1`: General error
230
- `2`: Command parsing error