0
# Self Management
1

2
UV provides built-in self-management capabilities for updating to the latest versions, checking version information, and maintaining the UV installation itself. These features ensure you always have access to the latest performance improvements and features.
3

4
## Capabilities
5

6
### Self Update
7

8
Update UV to the latest available version with automatic detection and installation.
9

10
```bash { .api }
11
uv self update
12
# Updates uv to the latest version
13
# Downloads and installs the latest release
14

15
# Options:
16
# --prerelease           # Include pre-release versions
17
# --no-modify-path      # Don't update PATH during installation
18
# --token TOKEN         # GitHub token for API access
19
```
20

21
Usage examples:
22

23
```bash
24
# Update to latest stable version
25
uv self update
26

27
# Update to latest including pre-releases
28
uv self update --prerelease
29

30
# Update with custom GitHub token
31
uv self update --token ghp_xxxxxxxxxxxx
32
```
33

34
### Version Information
35

36
Display detailed version and build information for UV installation.
37

38
```bash { .api }
39
uv self version
40
# Shows detailed version information
41
# Includes build date, commit hash, and platform info
42

43
# Options:
44
# --format FORMAT       # Output format (text/json)
45
```
46

47
Usage examples:
48

49
```bash
50
# Show version information
51
uv self version
52

53
# Get machine-readable version info
54
uv self version --format json
55

56
# Quick version check
57
uv --version
58
```
59

60
## Update Mechanisms
61

62
### Standalone Installer Updates
63

64
For UV installed via the standalone installer:
65

66
```bash { .api }
67
# Self-update is available and recommended
68
uv self update
69

70
# Update checks GitHub releases automatically
71
# Downloads platform-specific binary
72
# Replaces current installation atomically
73
```
74

75
### Package Manager Updates
76

77
For UV installed via package managers:
78

79
```bash { .api }
80
# pip installation
81
pip install --upgrade uv
82

83
# pipx installation
84
pipx upgrade uv
85

86
# Homebrew (macOS)
87
brew upgrade uv
88

89
# Cargo installation
90
cargo install uv --force
91
```
92

93
Note: `uv self update` may not be available for package manager installations.
94

95
## Version Detection
96

97
UV automatically detects the installation method and provides appropriate update mechanisms:
98

99
### Installation Methods
100

101
```bash { .api }
102
# Check installation method
103
uv self version
104

105
# Standalone installer: Shows self-update capability
106
# Package manager: Shows package manager info
107
# Development build: Shows build information
108
```
109

110
### Update Notifications
111

112
UV may display update notifications when newer versions are available:
113

114
```text { .api }
115
A newer version of uv is available: 0.8.19 (current: 0.8.18)
116
Run `uv self update` to update to the latest version.
117
```
118

119
Disable update notifications:
120

121
```bash { .api }
122
UV_NO_UPDATE_CHECK=1
123
```
124

125
## Release Information
126

127
UV follows semantic versioning and provides detailed release information:
128

129
### Version Format
130

131
```text { .api }
132
MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD]
133

134
Examples:
135
0.8.18              # Stable release
136
0.9.0-rc.1          # Release candidate
137
0.8.19-dev+abc123   # Development build
138
```
139

140
### Release Channels
141

142
- **Stable**: Fully tested releases for production use
143
- **Pre-release**: Beta and release candidate versions
144
- **Development**: Nightly and feature branch builds
145

146
### Release Notes
147

148
Access release information:
149

150
```bash
151
# Check latest releases on GitHub
152
open https://github.com/astral-sh/uv/releases
153

154
# View changelog
155
open https://github.com/astral-sh/uv/blob/main/CHANGELOG.md
156
```
157

158
## Configuration
159

160
Configure self-management behavior through UV settings:
161

162
```toml { .api }
163
[tool.uv]
164
# Self-update settings
165
self-update-check = true            # Check for updates automatically
166
self-update-prerelease = false      # Include pre-releases in updates
167
self-update-github-token = "token"  # GitHub token for API access
168
```
169

170
Environment variables:
171

172
```bash { .api }
173
UV_NO_UPDATE_CHECK=1               # Disable update checks
174
UV_GITHUB_TOKEN=ghp_xxxxxxx        # GitHub token for API access
175
UV_PRERELEASE=1                    # Include pre-releases
176
```
177

178
## Build Information
179

180
UV provides detailed build and runtime information:
181

182
### Build Details
183

184
```bash { .api }
185
uv self version --format json
186
```
187

188
Returns information including:
189
- Version number and build date
190
- Git commit hash and branch
191
- Rust compiler version
192
- Target platform and architecture
193
- Feature flags and compilation options
194

195
### Runtime Information
196

197
```bash { .api }
198
# Check UV executable location
199
which uv
200

201
# Check installation directory
202
dirname "$(which uv)"
203

204
# Check file information
205
ls -la "$(which uv)"
206
file "$(which uv)"
207
```
208

209
## Installation Verification
210

211
Verify UV installation integrity and functionality:
212

213
### Basic Verification
214

215
```bash { .api }
216
# Test basic functionality
217
uv --version
218
uv --help
219

220
# Test core commands
221
uv python list
222
uv cache dir
223

224
# Test package operations
225
uv pip list
226
```
227

228
### Advanced Verification
229

230
```bash { .api }
231
# Check all entry points
232
ls -la "$(dirname "$(which uv)")"
233

234
# Verify checksums (for standalone installations)
235
# Check against published checksums on GitHub releases
236

237
# Test critical functionality
238
uv venv test-env
239
uv pip install -e . --target test-env
240
rm -rf test-env
241
```
242

243
## Troubleshooting Self-Management
244

245
### Update Failures
246

247
```bash { .api }
248
# Check network connectivity
249
curl -s https://api.github.com/repos/astral-sh/uv/releases/latest
250

251
# Check file permissions
252
ls -la "$(which uv)"
253

254
# Manual update fallback
255
curl -LsSf https://astral.sh/uv/install.sh | sh
256
```
257

258
### Version Conflicts
259

260
```bash { .api }
261
# Check for multiple UV installations
262
which -a uv
263
find /usr -name "uv" 2>/dev/null
264

265
# Check PATH for conflicts
266
echo $PATH | tr ':' '\n' | grep -E "(uv|\.local|\.cargo)"
267

268
# Resolve conflicts by updating PATH or removing duplicates
269
```
270

271
### Permission Issues
272

273
```bash { .api }
274
# Check installation permissions
275
ls -la "$(dirname "$(which uv)")"
276

277
# For user installations, ensure proper permissions
278
chmod +x "$(which uv)"
279

280
# For system installations, may require sudo
281
sudo uv self update
282
```
283

284
## Integration with Package Managers
285

286
### Homebrew (macOS)
287

288
```bash { .api }
289
# Install
290
brew install uv
291

292
# Update
293
brew upgrade uv
294

295
# Check version
296
brew list uv --versions
297
```
298

299
### APT (Ubuntu/Debian)
300

301
```bash { .api }
302
# Add repository
303
curl -LsSf https://astral.sh/uv/install.sh | sh
304

305
# Or use system package if available
306
sudo apt update && sudo apt install uv
307
```
308

309
### Scoop (Windows)
310

311
```powershell { .api }
312
# Install
313
scoop install uv
314

315
# Update
316
scoop update uv
317

318
# Check version
319
scoop info uv
320
```
321

322
### Chocolatey (Windows)
323

324
```powershell { .api }
325
# Install
326
choco install uv
327

328
# Update
329
choco upgrade uv
330

331
# Check version
332
choco info uv
333
```
334

335
## Development Builds
336

337
For development and testing with unreleased features:
338

339
```bash { .api }
340
# Install from main branch
341
cargo install uv --git https://github.com/astral-sh/uv.git
342

343
# Install specific commit
344
cargo install uv --git https://github.com/astral-sh/uv.git --rev abc123
345

346
# Build from source
347
git clone https://github.com/astral-sh/uv.git
348
cd uv
349
cargo build --release
350
```
351

352
## Security Considerations
353

354
### Update Security
355

356
- UV updates are signed and verified
357
- Downloads use HTTPS with certificate verification
358
- GitHub releases include checksums for verification
359
- Self-update process is atomic (complete or rollback)
360

361
### Best Practices
362

363
```bash { .api }
364
# Regular updates for security patches
365
uv self update
366

367
# Verify installation integrity
368
uv self version
369

370
# Use stable releases for production
371
uv self update  # (avoids pre-releases by default)
372

373
# Monitor security advisories
374
# https://github.com/astral-sh/uv/security/advisories
375
```