0
# Python Management
1

2
UV provides comprehensive Python version discovery, installation, and management with support for multiple implementations (CPython, PyPy, GraalPy) and automatic downloads from official sources. It handles Python environments transparently while allowing explicit version control when needed.
3

4
## Capabilities
5

6
### Python Discovery and Listing
7

8
List and discover Python installations across the system with detailed version and implementation information.
9

10
```bash { .api }
11
uv python list
12
uv python ls                    # Alias for list
13
# Lists all discovered Python installations
14
# Shows version, implementation, and path information
15

16
# Options:
17
# --only-installed      # Show only uv-managed installations
18
# --format FORMAT       # Output format (text/json)
19
```
20

21
Usage examples:
22

23
```bash
24
# List all Python installations
25
uv python list
26

27
# List only uv-managed Python versions
28
uv python list --only-installed
29

30
# Get machine-readable output
31
uv python list --format json
32
```
33

34
### Python Installation
35

36
Download and install Python versions from official sources with automatic platform detection and optimization.
37

38
```bash { .api }
39
uv python install VERSION...
40
# Downloads and installs Python versions
41
# Supports multiple implementations and versions
42

43
# Version formats:
44
# 3.12                  # Latest patch of 3.12
45
# 3.12.1               # Specific version
46
# cpython@3.12         # CPython implementation
47
# pypy@3.10            # PyPy implementation
48
# graalpy@3.11         # GraalPy implementation
49
# cpython-3.12-macos-aarch64  # Platform-specific
50

51
# Options:
52
# --force              # Reinstall if already installed
53
# --python-preference  # Installation preference
54
```
55

56
Usage examples:
57

58
```bash
59
# Install latest Python 3.12
60
uv python install 3.12
61

62
# Install specific version
63
uv python install 3.12.1
64

65
# Install multiple versions
66
uv python install 3.11 3.12 3.13
67

68
# Install PyPy
69
uv python install pypy@3.10
70

71
# Force reinstall
72
uv python install 3.12 --force
73
```
74

75
### Python Discovery and Search
76

77
Find Python installations on the system based on version requests and implementation preferences.
78

79
```bash { .api }
80
uv python find [REQUEST]
81
# Finds Python installation matching request
82
# Uses discovery rules and preferences
83

84
# Request formats:
85
# 3.12                 # Version requirement
86
# >=3.11,<3.13        # Version range
87
# cpython             # Implementation
88
# cpython@3.12        # Implementation + version
89
# /path/to/python     # Specific executable
90

91
# Options:
92
# --format FORMAT     # Output format (text/json)
93
```
94

95
Usage examples:
96

97
```bash
98
# Find any Python 3.12
99
uv python find 3.12
100

101
# Find CPython 3.12
102
uv python find cpython@3.12
103

104
# Find Python with version range
105
uv python find ">=3.11,<3.13"
106

107
# Find specific executable
108
uv python find /usr/bin/python3
109
```
110

111
### Python Version Pinning
112

113
Pin projects to specific Python versions with .python-version file management.
114

115
```bash { .api }
116
uv python pin VERSION
117
# Creates/updates .python-version file
118
# Affects project's Python version resolution
119

120
# Options:
121
# --resolved          # Pin to resolved version
122
```
123

124
Usage examples:
125

126
```bash
127
# Pin to Python 3.12
128
uv python pin 3.12
129

130
# Pin to specific patch version
131
uv python pin 3.12.1
132

133
# Pin to resolved version
134
uv python pin 3.12 --resolved
135
```
136

137
### Python Directory Management
138

139
Show and manage Python installation directories and metadata.
140

141
```bash { .api }
142
uv python dir
143
# Shows Python installation directory
144
# Location where uv manages Python installations
145

146
# Options:
147
# --bin               # Show binary directory
148
```
149

150
Usage examples:
151

152
```bash
153
# Show Python installation directory
154
uv python dir
155

156
# Show Python binary directory
157
uv python dir --bin
158
```
159

160
### Python Version Upgrades
161

162
Upgrade installed Python versions to latest available releases.
163

164
```bash { .api }
165
uv python upgrade [VERSION...]
166
# Upgrades Python installations to latest versions
167
# Downloads and installs newer releases
168

169
# Options:
170
# --all               # Upgrade all installed versions
171
```
172

173
Usage examples:
174

175
```bash
176
# Upgrade specific version
177
uv python upgrade 3.12
178

179
# Upgrade all installed versions
180
uv python upgrade --all
181
```
182

183
### Python Uninstallation
184

185
Remove uv-managed Python installations to free disk space.
186

187
```bash { .api }
188
uv python uninstall VERSION...
189
# Removes uv-managed Python installations
190
# Does not affect system Python installations
191

192
# Options:
193
# --all               # Uninstall all managed versions
194
```
195

196
Usage examples:
197

198
```bash
199
# Uninstall specific version
200
uv python uninstall 3.11
201

202
# Uninstall multiple versions
203
uv python uninstall 3.10 3.11
204

205
# Uninstall all managed versions
206
uv python uninstall --all
207
```
208

209
## Python Discovery Rules
210

211
UV follows a systematic approach to finding Python installations:
212

213
1. **Virtual Environment**: Check active virtual environment or .venv in project hierarchy
214
2. **Project Pin**: Use .python-version file if present
215
3. **uv-managed**: Search uv-managed Python installations
216
4. **System PATH**: Search PATH environment variable for Python executables
217
5. **Platform-specific**: Check Windows registry, macOS framework locations
218
6. **Download**: Automatically download if enabled and version not found
219

220
## Python Version Request Formats
221

222
UV supports flexible Python version specification:
223

224
```bash { .api }
225
# Version patterns:
226
3                     # Latest Python 3.x
227
3.12                  # Latest Python 3.12.x
228
3.12.1               # Specific version 3.12.1
229

230
# Version specifiers:
231
>=3.11               # Minimum version
232
>=3.11,<3.13        # Version range
233
~=3.12.0            # Compatible release
234

235
# Implementation patterns:
236
cpython              # CPython implementation
237
cp                   # CPython (short)
238
pypy                 # PyPy implementation
239
graalpy              # GraalPy implementation
240

241
# Implementation + version:
242
cpython@3.12         # CPython 3.12
243
pypy@3.10           # PyPy 3.10
244
cpython3.12         # CPython 3.12 (alternate)
245
cp312               # CPython 3.12 (short)
246

247
# Platform-specific:
248
cpython-3.12.1-macos-aarch64-none
249
cpython-3.12.1-linux-x86_64-gnu
250
cpython-3.12.1-windows-x86_64-none
251

252
# Path-based:
253
/usr/bin/python3     # Absolute path
254
python3.12          # Executable name
255
/opt/python/        # Installation directory
256
```
257

258
## Global Python Configuration
259

260
Control Python behavior through global options and environment variables:
261

262
```bash { .api }
263
# Global options:
264
--python VERSION             # Specify Python version
265
--managed-python            # Require uv-managed Python
266
--no-managed-python         # Disable uv-managed Python
267
--no-python-downloads       # Disable automatic downloads
268

269
# Environment variables:
270
UV_PYTHON_PREFERENCE=managed    # Prefer managed Python
271
UV_PYTHON_DOWNLOADS=never      # Disable downloads
272
UV_MANAGED_PYTHON=true         # Force managed Python
273
```
274

275
## Python Version Configuration
276

277
Configure Python preferences in uv.toml:
278

279
```toml { .api }
280
[tool.uv]
281
python-preference = "managed"    # managed, system, or only-managed
282
python-downloads = "automatic"   # automatic, manual, or never
283

284
[tool.uv.sources]
285
python = "3.12"                 # Default Python version
286
```
287

288
Project-specific Python version in .python-version:
289

290
```text { .api }
291
3.12.1
292
```
293

294
## Supported Python Implementations
295

296
UV supports these Python implementations:
297

298
- **CPython**: Official Python implementation (most common)
299
- **PyPy**: Fast Python implementation with JIT compiler
300
- **GraalPy**: GraalVM-based Python implementation
301

302
Unsupported implementations are skipped during discovery, and requesting them results in an error.