0
# Pip Interface
1

2
UV provides a high-performance, pip-compatible interface that serves as a drop-in replacement for common pip workflows. The `uv pip` commands offer 10-100x faster performance while maintaining compatibility with existing requirements files, constraints, and pip conventions.
3

4
## Capabilities
5

6
### Package Installation
7

8
Install Python packages from PyPI, Git repositories, local paths, and other sources with fast dependency resolution.
9

10
```bash { .api }
11
uv pip install PACKAGE...
12
# Installs packages into current environment
13
# Supports all pip package specification formats
14

15
# Package specification formats:
16
# package                    # Latest version
17
# package==1.0.0            # Exact version
18
# package>=1.0.0,<2.0.0     # Version constraints
19
# package[extra]            # With optional dependencies
20
# git+https://github.com/user/repo.git  # Git repository
21
# git+https://github.com/user/repo.git@branch  # Git branch/tag
22
# https://example.com/package.whl  # Direct URL
23
# ./path/to/package         # Local path
24
# -e ./path/to/package      # Editable install
25

26
# Options:
27
# -r, --requirement FILE    # Install from requirements file
28
# -c, --constraint FILE     # Apply constraints file
29
# -e, --editable           # Install as editable
30
# --extra EXTRA            # Install optional dependencies
31
# --all-extras             # Install all optional dependencies
32
# --no-deps                # Don't install dependencies
33
# --force-reinstall        # Force reinstall packages
34
# --no-build-isolation     # Disable build isolation
35
# --no-index              # Ignore package index
36
# --find-links URL        # Additional package locations
37
# --index-url URL         # Base URL for package index
38
# --extra-index-url URL   # Extra package index URLs
39
# --trusted-host HOST     # Trust host for HTTP
40
# --pre                   # Include pre-release versions
41
# --python VERSION        # Target Python version
42
```
43

44
Usage examples:
45

46
```bash
47
# Install single package
48
uv pip install requests
49

50
# Install with version constraints
51
uv pip install "django>=4.0,<5.0"
52

53
# Install from requirements file
54
uv pip install -r requirements.txt
55

56
# Install with extras
57
uv pip install "fastapi[all]"
58

59
# Install from Git
60
uv pip install git+https://github.com/psf/requests.git
61

62
# Install editable local package
63
uv pip install -e ./my-package
64

65
# Install with constraints
66
uv pip install -r requirements.txt -c constraints.txt
67
```
68

69
### Package Uninstallation
70

71
Remove packages and their dependencies from the current environment.
72

73
```bash { .api }
74
uv pip uninstall PACKAGE...
75
# Uninstalls packages from current environment
76

77
# Options:
78
# -r, --requirement FILE    # Uninstall from requirements file
79
# -y, --yes                # Don't prompt for confirmation
80
```
81

82
Usage examples:
83

84
```bash
85
# Uninstall single package
86
uv pip uninstall requests
87

88
# Uninstall multiple packages
89
uv pip uninstall requests urllib3
90

91
# Uninstall from requirements file
92
uv pip uninstall -r requirements.txt
93

94
# Uninstall without confirmation
95
uv pip uninstall -y requests
96
```
97

98
### Requirements Compilation
99

100
Compile requirements.in files into locked requirements.txt files with resolved dependencies and hashes.
101

102
```bash { .api }
103
uv pip compile INPUT_FILE...
104
# Compiles requirements files with locked versions
105
# Resolves all transitive dependencies
106

107
# Input formats:
108
# requirements.in          # Basic requirements file
109
# pyproject.toml          # Extract from project dependencies
110
# setup.py                # Extract from setup.py
111
# setup.cfg               # Extract from setup.cfg
112

113
# Options:
114
# -o, --output-file FILE   # Output file (default: requirements.txt)
115
# --upgrade               # Upgrade all dependencies
116
# --upgrade-package PKG   # Upgrade specific packages
117
# -c, --constraint FILE   # Apply constraints
118
# --extra EXTRA          # Include optional dependencies
119
# --all-extras           # Include all optional dependencies
120
# --annotation-style STYLE  # Annotation style (line/split)
121
# --header               # Include header in output
122
# --no-header           # Exclude header from output
123
# --index-url URL       # Base package index URL
124
# --extra-index-url URL # Extra package index URLs
125
# --find-links URL      # Additional package locations
126
# --no-index           # Ignore package index
127
# --generate-hashes    # Generate hashes for packages
128
# --python VERSION     # Target Python version
129
# --resolution MODE    # Resolution strategy (highest/lowest-direct)
130
```
131

132
Usage examples:
133

134
```bash
135
# Compile requirements.in to requirements.txt
136
uv pip compile requirements.in
137

138
# Compile with custom output file
139
uv pip compile requirements.in -o prod-requirements.txt
140

141
# Compile pyproject.toml dependencies
142
uv pip compile pyproject.toml
143

144
# Upgrade all dependencies
145
uv pip compile requirements.in --upgrade
146

147
# Upgrade specific packages
148
uv pip compile requirements.in --upgrade-package requests
149

150
# Include optional dependencies
151
uv pip compile requirements.in --extra dev
152

153
# Generate with hashes
154
uv pip compile requirements.in --generate-hashes
155
```
156

157
### Environment Synchronization
158

159
Synchronize the current environment to exactly match a requirements file, adding and removing packages as needed.
160

161
```bash { .api }
162
uv pip sync REQUIREMENTS_FILE...
163
# Synchronizes environment with requirements file
164
# Installs missing packages, removes extras
165

166
# Options:
167
# -c, --constraint FILE    # Apply constraints file
168
# --reinstall             # Reinstall all packages
169
# --find-links URL        # Additional package locations
170
# --index-url URL         # Base package index URL
171
# --extra-index-url URL   # Extra package index URLs
172
# --no-index             # Ignore package index
173
# --trusted-host HOST    # Trust host for HTTP
174
# --python VERSION       # Target Python version
175
```
176

177
Usage examples:
178

179
```bash
180
# Sync with requirements file
181
uv pip sync requirements.txt
182

183
# Sync with constraints
184
uv pip sync requirements.txt -c constraints.txt
185

186
# Reinstall all packages during sync
187
uv pip sync requirements.txt --reinstall
188

189
# Sync multiple requirements files
190
uv pip sync requirements.txt dev-requirements.txt
191
```
192

193
### Package Listing and Inspection
194

195
List installed packages and show detailed package information.
196

197
```bash { .api }
198
uv pip list
199
uv pip ls                       # Alias for list
200
# Lists installed packages in tabular format
201

202
# Options:
203
# --format FORMAT         # Output format (columns/freeze/json)
204
# --exclude PACKAGE       # Exclude packages from output
205
# --outdated             # Show outdated packages only
206
```
207

208
```bash { .api }
209
uv pip freeze
210
# Lists installed packages in requirements format
211
# Compatible with pip freeze output
212

213
# Options:
214
# --exclude-editable     # Exclude editable packages
215
```
216

217
```bash { .api }
218
uv pip show PACKAGE...
219
# Shows detailed information about packages
220

221
# Options:
222
# --files                # Show installed files
223
```
224

225
Usage examples:
226

227
```bash
228
# List all packages in table format
229
uv pip list
230

231
# List packages in freeze format
232
uv pip freeze
233

234
# List in JSON format
235
uv pip list --format json
236

237
# Show outdated packages
238
uv pip list --outdated
239

240
# Show package details
241
uv pip show requests
242

243
# Show package with files
244
uv pip show requests --files
245
```
246

247
### Dependency Tree Visualization
248

249
Display dependency relationships in tree format for better understanding of package dependencies.
250

251
```bash { .api }
252
uv pip tree
253
# Shows dependency tree for installed packages
254

255
# Options:
256
# --depth DEPTH          # Maximum display depth
257
# --prune PACKAGE        # Prune specific packages from tree
258
# --package PACKAGE      # Show tree for specific package only
259
# --reverse             # Show reverse dependencies
260
```
261

262
Usage examples:
263

264
```bash
265
# Show full dependency tree
266
uv pip tree
267

268
# Show tree with limited depth
269
uv pip tree --depth 2
270

271
# Show dependencies for specific package
272
uv pip tree --package requests
273

274
# Show what depends on a package
275
uv pip tree --reverse --package urllib3
276
```
277

278
### Dependency Validation
279

280
Check installed packages for dependency conflicts and compatibility issues.
281

282
```bash { .api }
283
uv pip check
284
# Verifies installed packages have compatible dependencies
285
# Reports conflicts and missing dependencies
286

287
# Exit codes:
288
# 0: No issues found
289
# 1: Issues found
290
```
291

292
Usage examples:
293

294
```bash
295
# Check for dependency conflicts
296
uv pip check
297

298
# Use in CI/CD pipelines
299
uv pip check && echo "Dependencies OK"
300
```
301

302
## Index and Repository Configuration
303

304
Configure package indexes and repositories for private packages and mirrors:
305

306
```bash { .api }
307
# Index options (available for install, compile, sync):
308
--index-url URL              # Primary package index
309
--extra-index-url URL        # Additional package indexes
310
--find-links URL             # Local package directories or URLs
311
--no-index                   # Disable all package indexes
312
--trusted-host HOST          # Trust HTTP connections to host
313
```
314

315
Common configurations:
316

317
```bash
318
# Use private PyPI mirror
319
uv pip install requests --index-url https://pypi.company.com/simple/
320

321
# Use multiple indexes
322
uv pip install requests --extra-index-url https://test.pypi.org/simple/
323

324
# Use local package directory
325
uv pip install mypackage --find-links ./dist/
326

327
# Trust internal host
328
uv pip install requests --trusted-host internal.pypi.org
329
```
330

331
## Requirements File Format
332

333
UV supports standard pip requirements file syntax with extensions:
334

335
```text { .api }
336
# requirements.txt
337
requests>=2.25.0
338
numpy==1.21.0
339
pandas>=1.3.0,<2.0.0
340

341
# With extras
342
fastapi[all]>=0.68.0
343

344
# Git dependencies
345
git+https://github.com/user/repo.git@v1.0.0#egg=package
346

347
# Local paths
348
-e ./local-package
349

350
# URLs
351
https://files.pythonhosted.org/packages/.../package.whl
352

353
# Include other files
354
-r dev-requirements.txt
355

356
# Constraints files
357
-c constraints.txt
358

359
# Index configuration
360
--index-url https://pypi.org/simple/
361
--extra-index-url https://test.pypi.org/simple/
362
--find-links https://download.pytorch.org/whl/torch_stable.html
363
--trusted-host download.pytorch.org
364
```
365

366
## Constraint Files
367

368
Constraint files limit package versions without requiring installation:
369

370
```text { .api }
371
# constraints.txt
372
# Pin transitive dependencies
373
urllib3==1.26.12
374
certifi==2022.9.24
375

376
# Version bounds
377
cryptography>=3.0,<4.0
378
```
379

380
Usage with constraints:
381

382
```bash
383
uv pip install -r requirements.txt -c constraints.txt
384
uv pip compile requirements.in -c constraints.txt
385
```
386

387
## Resolution Strategies
388

389
UV supports different dependency resolution modes:
390

391
```bash { .api }
392
--resolution MODE
393
# highest (default): Prefer highest versions
394
# lowest-direct: Use lowest versions for direct dependencies
395
```
396

397
This helps test compatibility with minimum supported versions:
398

399
```bash
400
# Test with minimum versions
401
uv pip compile requirements.in --resolution lowest-direct
402
```
403

404
## Build Configuration
405

406
Control package building and compilation:
407

408
```bash { .api }
409
# Build options:
410
--no-build-isolation        # Disable build environment isolation
411
--no-binary PACKAGE         # Disable binary packages
412
--only-binary PACKAGE       # Only use binary packages
413
--config-settings KEY=VALUE # Pass settings to build backend
414
```
415

416
Examples:
417

418
```bash
419
# Force source builds
420
uv pip install numpy --no-binary numpy
421

422
# Only use wheels
423
uv pip install --only-binary :all: numpy
424

425
# Pass build settings
426
uv pip install package --config-settings="--build-option=--debug"
427
```