0
# Project Management
1

2
UV provides comprehensive project lifecycle management with pyproject.toml-based configuration, universal lockfiles, and Cargo-style workspace support. Projects use modern Python packaging standards with fast dependency resolution and cross-platform compatibility.
3

4
## Capabilities
5

6
### Project Initialization
7

8
Create new Python projects with pyproject.toml configuration and basic project structure.
9

10
```bash { .api }
11
uv init [PATH]
12
# Creates new project directory with:
13
# - pyproject.toml
14
# - README.md (unless --no-readme or --bare)
15
# - src/package/ directory structure (unless --bare)
16
# - .gitignore (unless --bare)
17
# - .python-version (unless --no-pin-python or --bare)
18

19
# Options:
20
# --name NAME              # Project name
21
# --bare                   # Only create pyproject.toml
22
# --package                # Create package structure (default)
23
# --no-package            # Don't set up as package
24
# --lib                    # Create library package
25
# --app                    # Create application package
26
# --script                 # Create PEP 723 script with inline metadata
27
# --description DESC       # Set project description
28
# --no-description        # Disable description for project
29
# --vcs {git,none}        # Initialize version control system (default: git)
30
# --build-backend BACKEND  # Initialize build backend (implies --package)
31
# --author-from {auto,git,none} # Fill authors field (default: auto)
32
# --no-readme             # Skip README.md creation
33
# --no-pin-python         # Don't pin Python version
34
# --no-workspace          # Avoid discovering workspace, create standalone
35
# --python VERSION        # Python version to use
36
```
37

38
Usage examples:
39

40
```bash
41
# Create new project in current directory
42
uv init
43

44
# Create project in specific directory
45
uv init my-project
46

47
# Create library with specific name
48
uv init --lib my-library --name mylib
49

50
# Create app with Python version
51
uv init my-app --app --python 3.12
52

53
# Create bare project (only pyproject.toml)
54
uv init --bare
55

56
# Create PEP 723 script
57
uv init script.py --script
58

59
# Create project with specific description and build backend
60
uv init my-lib --lib --description "My library" --build-backend setuptools
61
```
62

63
### Dependency Management
64

65
Add and remove project dependencies with automatic lockfile updates and conflict resolution.
66

67
```bash { .api }
68
uv add PACKAGE...
69
# Adds packages to pyproject.toml dependencies
70
# Updates uv.lock with resolved versions
71
# Installs packages in project environment
72

73
# Package specification formats:
74
# package                  # Latest version
75
# package==1.0.0          # Exact version
76
# package>=1.0.0          # Version constraint
77
# package[extra]          # With extra features
78
# git+https://...         # Git repository
79
# path/to/local           # Local path
80
# -e path/to/editable     # Editable install
81

82
# Options:
83
# --requirements, -r FILE  # Add packages from requirements file
84
# --constraints, -c FILE   # Apply version constraints from file
85
# --marker, -m MARKER      # Apply marker expression to packages
86
# --dev                    # Add to dev dependencies (alias for --group dev)
87
# --optional GROUP         # Add to optional dependency group
88
# --group GROUP            # Add to specified dependency group
89
# --editable               # Add as editable dependency
90
# --raw                    # Add dependency without bounds or to tool.uv.sources
91
# --bounds {exact,compatible,lowest-direct} # Version specifier type
92
# --rev REV                # Git commit to use
93
# --tag TAG                # Git tag to use
94
# --branch BRANCH          # Git branch to use
95
# --extra EXTRA            # Enable extras for dependency
96
# --no-sync                # Don't sync after adding
97
# --locked                 # Assert lockfile remains unchanged
98
# --frozen                 # Add without re-locking
99
# --active                 # Prefer active virtual environment
100
# --package PACKAGE        # Add to specific workspace package
101
# --script SCRIPT          # Add to PEP 723 script metadata
102
# --workspace              # Add as workspace member
103
# --no-workspace           # Don't add as workspace member
104
# --python VERSION         # Python version to use
105
```
106

107
```bash { .api }
108
uv remove PACKAGE...
109
# Removes packages from pyproject.toml
110
# Updates uv.lock
111
# Uninstalls from project environment
112

113
# Options:
114
# --dev                  # Remove from dev dependencies (alias for --group dev)
115
# --optional GROUP       # Remove from optional dependency group
116
# --group GROUP          # Remove from specified dependency group
117
# --no-sync             # Don't sync after removing
118
# --locked              # Assert lockfile remains unchanged
119
# --frozen              # Remove without re-locking
120
# --active              # Prefer active virtual environment
121
# --package PACKAGE     # Remove from specific workspace package
122
# --script SCRIPT       # Remove from PEP 723 script metadata
123
# --python VERSION      # Python version to use
124
```
125

126
Usage examples:
127

128
```bash
129
# Add production dependencies
130
uv add requests numpy pandas
131

132
# Add development dependencies
133
uv add --dev pytest black ruff
134

135
# Add with version constraints
136
uv add "django>=4.0,<5.0"
137

138
# Add with extras
139
uv add "fastapi[all]"
140

141
# Add git dependency
142
uv add git+https://github.com/user/repo.git
143

144
# Add git dependency with specific branch
145
uv add git+https://github.com/user/repo.git --branch feature
146

147
# Add from requirements file
148
uv add -r requirements.txt
149

150
# Add to optional dependency group
151
uv add --optional test pytest pytest-cov
152

153
# Add to custom group
154
uv add --group docs mkdocs sphinx
155

156
# Add with marker
157
uv add --marker "sys_platform == 'win32'" pywin32
158

159
# Add to workspace package
160
uv add --package my-package requests
161

162
# Add to script metadata
163
uv add --script myscript.py requests
164

165
# Remove dependencies
166
uv remove requests
167
uv remove --dev pytest
168

169
# Remove from specific group
170
uv remove --group docs sphinx
171

172
# Remove from optional dependency group
173
uv remove --optional test pytest-cov
174

175
# Remove from workspace package
176
uv remove --package my-package requests
177
```
178

179
### Environment Synchronization
180

181
Update project environment to match the lockfile, ensuring consistent dependency versions across environments.
182

183
```bash { .api }
184
uv sync
185
# Synchronizes environment with uv.lock
186
# Installs/updates/removes packages as needed
187
# Creates virtual environment if missing
188

189
# Options:
190
# --dev                   # Include dev dependencies
191
# --all-extras           # Include all optional groups
192
# --extra EXTRA          # Include specific extras
193
# --only-dev             # Install only dev dependencies
194
# --frozen               # Use exact lockfile versions
195
# --no-install-project   # Don't install project itself
196
# --no-editable          # Install project non-editably
197
# --python VERSION       # Python version to use
198
```
199

200
Usage examples:
201

202
```bash
203
# Sync production dependencies
204
uv sync
205

206
# Sync with dev dependencies
207
uv sync --dev
208

209
# Sync specific extras
210
uv sync --extra testing --extra docs
211

212
# Sync only dev dependencies
213
uv sync --only-dev
214

215
# Sync with exact lockfile versions
216
uv sync --frozen
217
```
218

219
### Command Execution
220

221
Run commands and scripts in the project environment with automatic environment activation and path management.
222

223
```bash { .api }
224
uv run COMMAND [ARGS...]
225
# Executes command in project environment
226
# Activates virtual environment automatically
227
# Supports scripts defined in pyproject.toml
228

229
# Options:
230
# --python VERSION       # Python version to use
231
# --with PACKAGE         # Add temporary dependencies
232
# --no-sync             # Skip environment sync
233
# --isolated            # Run in isolated environment
234
# --frozen              # Use exact lockfile versions
235
```
236

237
Usage examples:
238

239
```bash
240
# Run Python script
241
uv run python main.py
242

243
# Run Python module
244
uv run python -m pytest
245

246
# Run project script (defined in pyproject.toml)
247
uv run dev
248

249
# Run with temporary dependencies
250
uv run --with requests python fetch_data.py
251

252
# Run without syncing
253
uv run --no-sync python quick_script.py
254
```
255

256
### Lockfile Management
257

258
Create and update universal lockfiles for reproducible dependency resolution across platforms and Python versions.
259

260
```bash { .api }
261
uv lock
262
# Updates uv.lock with current dependencies
263
# Resolves all transitive dependencies
264
# Generates cross-platform lock entries
265

266
# Options:
267
# --frozen              # Don't update dependencies
268
# --upgrade             # Upgrade all dependencies
269
# --upgrade-package PKG # Upgrade specific package
270
# --python VERSION      # Target Python version
271
```
272

273
Usage examples:
274

275
```bash
276
# Update lockfile
277
uv lock
278

279
# Lock without updating dependencies
280
uv lock --frozen
281

282
# Upgrade all dependencies
283
uv lock --upgrade
284

285
# Upgrade specific packages
286
uv lock --upgrade-package requests --upgrade-package numpy
287
```
288

289
### Export and Integration
290

291
Export project dependencies to various formats for integration with other tools and deployment pipelines.
292

293
```bash { .api }
294
uv export
295
# Exports dependencies from lockfile
296
# Supports multiple output formats
297

298
# Options:
299
# --format FORMAT        # Output format (requirements-txt, etc.)
300
# --output-file FILE     # Output file path
301
# --dev                  # Include dev dependencies
302
# --all-extras          # Include all extras
303
# --extra EXTRA         # Include specific extra
304
# --no-hashes          # Exclude hashes from output
305
# --frozen             # Use exact lockfile versions
306
```
307

308
Usage examples:
309

310
```bash
311
# Export to requirements.txt
312
uv export --format requirements-txt --output-file requirements.txt
313

314
# Export with dev dependencies
315
uv export --dev --format requirements-txt > requirements-dev.txt
316

317
# Export specific extras
318
uv export --extra testing --format requirements-txt
319
```
320

321
### Version Management
322

323
Manage project version information with automatic updates across project files.
324

325
```bash { .api }
326
uv version [VERSION]
327
# Shows or updates project version
328
# Updates pyproject.toml and other version files
329

330
# Options:
331
# --bump LEVEL          # Bump version (major/minor/patch)
332
```
333

334
Usage examples:
335

336
```bash
337
# Show current version
338
uv version
339

340
# Set specific version
341
uv version 1.2.3
342

343
# Bump patch version
344
uv version --bump patch
345

346
# Bump minor version
347
uv version --bump minor
348
```
349

350
### Dependency Tree Visualization
351

352
Display project dependency relationships and version information in tree format.
353

354
```bash { .api }
355
uv tree
356
# Shows dependency tree for project
357
# Displays version information and relationships
358

359
# Options:
360
# --depth DEPTH         # Maximum depth to display
361
# --prune PACKAGE       # Prune specific packages
362
# --package PACKAGE     # Show tree for specific package
363
# --universal           # Show universal tree
364
```
365

366
Usage examples:
367

368
```bash
369
# Show full dependency tree
370
uv tree
371

372
# Show tree with limited depth
373
uv tree --depth 2
374

375
# Show tree for specific package
376
uv tree --package requests
377

378
# Show universal tree
379
uv tree --universal
380
```
381

382
### Code Formatting
383

384
Format Python code in the project using integrated formatters with consistent configuration.
385

386
```bash { .api }
387
uv format [PATH...]
388
# Formats Python code in project
389
# Uses project configuration from pyproject.toml
390

391
# Options:
392
# --check               # Check formatting without changes
393
# --diff                # Show formatting changes
394
# --config-file FILE    # Configuration file path
395
```
396

397
Usage examples:
398

399
```bash
400
# Format entire project
401
uv format
402

403
# Format specific files
404
uv format src/main.py tests/
405

406
# Check formatting without changes
407
uv format --check
408

409
# Show formatting differences
410
uv format --diff
411
```
412

413
## Project Configuration
414

415
UV projects use standard pyproject.toml configuration:
416

417
```toml { .api }
418
[project]
419
name = "my-project"
420
version = "0.1.0"
421
description = "Project description"
422
dependencies = [
423
    "requests>=2.25.0",
424
    "numpy>=1.20.0",
425
]
426

427
[project.optional-dependencies]
428
dev = [
429
    "pytest>=7.0.0",
430
    "black>=22.0.0",
431
]
432
testing = [
433
    "pytest-cov>=4.0.0",
434
]
435

436
[project.scripts]
437
dev = "my_project.dev:main"
438
start = "my_project:main"
439

440
[tool.uv]
441
dev-dependencies = [
442
    "ruff>=0.1.0",
443
]
444

445
[tool.uv.workspace]
446
members = ["packages/*"]
447
```
448

449
## Workspace Support
450

451
UV supports Cargo-style workspaces for managing multiple packages:
452

453
```toml { .api }
454
# Root pyproject.toml
455
[tool.uv.workspace]
456
members = [
457
    "packages/*",
458
    "tools/cli",
459
]
460
exclude = [
461
    "packages/experimental",
462
]
463

464
# Package pyproject.toml
465
[project]
466
name = "package-name"
467

468
[tool.uv.sources]
469
shared-utils = { workspace = true }
470
```