0
# UV
1

2
An extremely fast Python package and project manager, written in Rust. UV serves as a comprehensive, drop-in replacement for multiple Python development tools including pip, poetry, pipx, virtualenv, pyenv, and twine, offering 10-100x faster performance while providing a unified interface for the complete Python development lifecycle.
3

4
## Package Information
5

6
- **Package Name**: uv
7
- **Language**: Rust (CLI tool distributed as Python package)
8
- **Installation**: `pip install uv` or `curl -LsSf https://astral.sh/uv/install.sh | sh`
9
- **Platform Support**: macOS, Linux, Windows
10
- **Python Support**: >=3.8
11

12
## Core Usage
13

14
UV is primarily used as a command-line tool:
15

16
```bash
17
# Install uv
18
pip install uv
19

20
# Or via standalone installer
21
curl -LsSf https://astral.sh/uv/install.sh | sh
22
```
23

24
Basic project workflow:
25

26
```bash
27
# Create a new project
28
uv init my-project
29
cd my-project
30

31
# Add dependencies
32
uv add requests numpy
33

34
# Install dependencies
35
uv sync
36

37
# Run a script
38
uv run python main.py
39

40
# Run a tool
41
uv tool run black .
42
```
43

44
## Architecture
45

46
UV provides a unified interface through multiple command namespaces:
47

48
- **Project Commands**: Complete project lifecycle management (init, add, remove, sync, run, lock, export)
49
- **Package Management**: Pip-compatible interface for environment management (pip install/uninstall/sync/compile)
50
- **Python Management**: Version discovery, installation, and switching (python install/list/find)
51
- **Tool Management**: Isolated tool installation and execution (tool install/run/list)
52
- **Build System**: Package building and publishing (build, publish)
53
- **Virtual Environments**: High-performance venv creation and management
54

55
This unified approach eliminates tool fragmentation while maintaining compatibility with existing Python ecosystems through pip-compatible interfaces and universal lockfile support.
56

57
## Capabilities
58

59
### Project Management
60

61
Complete project lifecycle management with pyproject.toml-based configuration, universal lockfiles, and workspace support similar to Cargo.
62

63
```bash { .api }
64
uv init [PATH]                    # Create new project
65
uv add PACKAGE...                 # Add dependencies
66
uv remove PACKAGE...              # Remove dependencies
67
uv sync                          # Update environment to match lockfile
68
uv run COMMAND                   # Run command in project environment
69
uv lock                          # Update project lockfile
70
uv export [--format FORMAT]      # Export lockfile to alternate formats
71
```
72

73
[Project Management](./project-management.md)
74

75
### Python Version Management
76

77
Automatic Python discovery, installation, and management with support for multiple implementations and versions.
78

79
```bash { .api }
80
uv python list                   # List available Python installations
81
uv python install VERSION       # Install Python version
82
uv python find [REQUEST]         # Find Python installation
83
uv python pin VERSION           # Pin project to Python version
84
```
85

86
[Python Management](./python-management.md)
87

88
### Package Installation (Pip-Compatible)
89

90
High-performance pip-compatible interface providing drop-in replacement for common pip workflows with universal resolution.
91

92
```bash { .api }
93
uv pip install PACKAGE...        # Install packages
94
uv pip uninstall PACKAGE...      # Uninstall packages
95
uv pip compile INPUT_FILE        # Compile requirements file
96
uv pip sync REQUIREMENTS_FILE    # Sync environment with requirements
97
uv pip list                      # List installed packages
98
uv pip freeze                    # Output installed packages in requirements format
99
```
100

101
[Pip Interface](./pip-interface.md)
102

103
### Tool Management
104

105
Isolated execution and installation of Python tools with automatic dependency resolution and global availability.
106

107
```bash { .api }
108
uv tool run TOOL [ARGS...]       # Run tool in isolated environment
109
uv tool install TOOL            # Install tool globally
110
uv tool list                     # List installed tools
111
uv tool uninstall TOOL          # Uninstall tool
112
```
113

114
[Tool Management](./tool-management.md)
115

116
### Virtual Environment Management
117

118
Fast virtual environment creation and management with automatic discovery and Python version selection.
119

120
```bash { .api }
121
uv venv [PATH]                   # Create virtual environment
122
```
123

124
[Virtual Environments](./virtual-environments.md)
125

126
### Build and Publishing
127

128
Package building into source distributions and wheels, plus publishing to PyPI and private indexes.
129

130
```bash { .api }
131
uv build [PATH]                  # Build packages
132
uv publish [DIST...]             # Publish to index
133
```
134

135
[Build System](./build-system.md)
136

137
### Authentication Management
138

139
Authentication handling for PyPI and private package indexes with secure credential storage.
140

141
```bash { .api }
142
uv auth login [SERVICE]          # Login to service
143
uv auth logout [SERVICE]         # Logout from service
144
uv auth token [SERVICE]          # Show authentication token
145
```
146

147
[Authentication](./authentication.md)
148

149
### Cache Management
150

151
Global cache management for packages and metadata with deduplication and cleanup utilities.
152

153
```bash { .api }
154
uv cache clean                   # Clear cache
155
uv cache prune                   # Prune unreachable cache objects
156
uv cache dir                     # Show cache directory
157
```
158

159
[Cache Management](./cache-management.md)
160

161
### Self Management
162

163
UV self-update and version management functionality.
164

165
```bash { .api }
166
uv self update                   # Update uv
167
uv self version                  # Show version information
168
```
169

170
[Self Management](./self-management.md)
171

172
### Utilities
173

174
Help system and completion utilities for enhanced user experience.
175

176
```bash { .api }
177
uv help [COMMAND]                # Display help for commands
178
uv generate-shell-completion     # Generate shell completion scripts
179
uv clean                         # Legacy alias for cache clean
180
```
181

182
## Global Options
183

184
All uv commands support these global options:
185

186
```bash { .api }
187
--help, -h                       # Show help
188
--version, -V                    # Show version
189
--quiet, -q                      # Quiet output (repeatable)
190
--verbose, -v                    # Verbose output (repeatable)
191
--color CHOICE                   # Color output (auto/always/never)
192
--no-color                       # Disable colors
193
--python VERSION                 # Python version to use
194
--config-file PATH               # Configuration file path
195
--no-config                      # Skip configuration discovery
196
--offline                        # Disable network access
197
--native-tls                     # Use system certificate store
198
--allow-insecure-host HOST       # Allow insecure connections
199
--directory PATH                 # Change directory before running
200
--project PATH                   # Project directory
201

202
# Exit codes:
203
# 0: Success
204
# 1: General error (command failed)
205
# 2: Usage error (invalid arguments)
206
```
207

208
## Configuration Files
209

210
UV uses these configuration files:
211

212
- **pyproject.toml**: Project configuration and dependencies
213
- **uv.toml**: UV-specific configuration
214
- **uv.lock**: Universal lockfile for dependencies
215
- **.python-version**: Python version specification
216

217
## Python Module Interface
218

219
When installed via pip, uv provides a Python module interface:
220

221
```python { .api }
222
# Available after: pip install uv
223
import uv
224

225
# Find uv binary location (returns pathlib.Path)
226
binary_path = uv.find_uv_bin()
227

228
# Module execution (delegates to native binary)
229
# python -m uv [commands...]
230
# Exit codes: 0 (success), 1 (error), 2 (usage error)
231

232
# Example usage:
233
import subprocess
234
result = subprocess.run(["python", "-m", "uv", "pip", "list"],
235
                       capture_output=True, text=True)
236
```
237

238
## Binary Entry Points
239

240
UV provides multiple entry points:
241

242
- **uv**: Main CLI interface with all functionality
243
- **uvx**: Shortcut for `uv tool run` - quickly run tools
244
- **uvw**: Windows-specific GUI wrapper
245

246
Example uvx usage:
247

248
```bash { .api }
249
uvx black .                      # Equivalent to: uv tool run black .
250
uvx ruff check                   # Equivalent to: uv tool run ruff check
251
```