0
# Authentication
1

2
UV provides secure authentication management for PyPI and private package indexes, supporting API tokens, username/password authentication, and keyring integration with encrypted credential storage.
3

4
## Capabilities
5

6
### Login Management
7

8
Authenticate with package indexes and store credentials securely for future operations.
9

10
```bash { .api }
11
uv auth login [SERVICE]
12
# Authenticates with a package index service
13
# Stores credentials securely for future use
14

15
# Services:
16
# pypi                    # PyPI (default)
17
# testpypi               # TestPyPI
18
# URL                    # Custom index URL
19

20
# Options:
21
# --username USERNAME    # Username for authentication
22
# --password PASSWORD    # Password for authentication
23
# --token TOKEN         # API token for authentication
24
# --keyring-provider    # Keyring provider to use
25
```
26

27
Usage examples:
28

29
```bash
30
# Login to PyPI with interactive prompts
31
uv auth login
32

33
# Login to PyPI with username/password
34
uv auth login --username myuser --password mypass
35

36
# Login with API token
37
uv auth login --token pypi-token-here
38

39
# Login to TestPyPI
40
uv auth login testpypi
41

42
# Login to private index
43
uv auth login https://private.pypi.org/simple/
44
```
45

46
### Logout Management
47

48
Remove stored credentials and invalidate authentication for package indexes.
49

50
```bash { .api }
51
uv auth logout [SERVICE]
52
# Removes stored credentials for service
53
# Invalidates authentication tokens where possible
54

55
# Services:
56
# pypi                   # PyPI (default)
57
# testpypi              # TestPyPI
58
# URL                   # Custom index URL
59
# --all                 # All configured services
60
```
61

62
Usage examples:
63

64
```bash
65
# Logout from PyPI
66
uv auth logout
67

68
# Logout from TestPyPI
69
uv auth logout testpypi
70

71
# Logout from private index
72
uv auth logout https://private.pypi.org/simple/
73

74
# Logout from all services
75
uv auth logout --all
76
```
77

78
### Token Management
79

80
Display and manage authentication tokens for troubleshooting and integration purposes.
81

82
```bash { .api }
83
uv auth token [SERVICE]
84
# Shows authentication token for service
85
# Useful for troubleshooting and CI/CD integration
86

87
# Options:
88
# --format FORMAT       # Output format (text/json)
89
```
90

91
Usage examples:
92

93
```bash
94
# Show PyPI token
95
uv auth token
96

97
# Show TestPyPI token
98
uv auth token testpypi
99

100
# Show token for private index
101
uv auth token https://private.pypi.org/simple/
102

103
# Get machine-readable output
104
uv auth token --format json
105
```
106

107
### Credential Directory
108

109
Manage authentication credential storage location and configuration.
110

111
```bash { .api }
112
uv auth dir
113
# Shows path to UV credentials directory
114
# Location where authentication data is stored
115
```
116

117
Usage examples:
118

119
```bash
120
# Show credentials directory
121
uv auth dir
122

123
# List credential files
124
ls "$(uv auth dir)"
125

126
# Backup credentials
127
cp -r "$(uv auth dir)" ~/uv-credentials-backup
128
```
129

130
## Authentication Methods
131

132
### API Token Authentication
133

134
Most secure method for PyPI and compatible indexes:
135

136
```bash { .api }
137
# Using API token (recommended)
138
uv auth login --token pypi-AgENdGVzdC5weXBpLm9yZw...
139

140
# Token format for PyPI:
141
# pypi-<token-data>
142

143
# Token format for TestPyPI:
144
# testpypi-<token-data>
145
```
146

147
### Username/Password Authentication
148

149
Traditional authentication method:
150

151
```bash { .api }
152
# Interactive prompts
153
uv auth login --username myuser
154
# Password: [hidden input]
155

156
# Non-interactive
157
uv auth login --username myuser --password mypassword
158
```
159

160
### Environment Variable Authentication
161

162
Configure authentication through environment variables:
163

164
```bash { .api }
165
# PyPI token
166
UV_PUBLISH_TOKEN=pypi-token-here
167

168
# Index-specific tokens
169
UV_INDEX_TOKEN_PYPI=pypi-token
170
UV_INDEX_TOKEN_TESTPYPI=testpypi-token
171

172
# Username/password
173
UV_PUBLISH_USERNAME=username
174
UV_PUBLISH_PASSWORD=password
175

176
# Index URL
177
UV_PUBLISH_URL=https://upload.pypi.org/legacy/
178
```
179

180
## Keyring Integration
181

182
UV integrates with system keyring services for secure credential storage:
183

184
### Supported Keyring Providers
185

186
```bash { .api }
187
# System keyring (default)
188
uv auth login --keyring-provider keyring
189

190
# Subprocess keyring
191
uv auth login --keyring-provider subprocess
192

193
# Disabled keyring
194
uv auth login --keyring-provider disabled
195
```
196

197
### Platform-Specific Keyring Support
198

199
- **macOS**: Keychain integration
200
- **Windows**: Windows Credential Store
201
- **Linux**: libsecret, KWallet, or encrypted files
202

203
### Keyring Configuration
204

205
Configure keyring behavior in UV settings:
206

207
```toml { .api }
208
[tool.uv]
209
keyring-provider = "keyring"        # keyring, subprocess, disabled
210
auth-cache-dir = "~/.uv/auth"      # Custom auth cache directory
211
```
212

213
## Index Configuration
214

215
Configure authentication for multiple package indexes:
216

217
### Global Index Authentication
218

219
```toml { .api }
220
# .pypirc configuration
221
[distutils]
222
index-servers =
223
    pypi
224
    testpypi
225
    private
226

227
[pypi]
228
repository = https://upload.pypi.org/legacy/
229
username = __token__
230
password = pypi-token
231

232
[testpypi]
233
repository = https://test.pypi.org/legacy/
234
username = __token__
235
password = testpypi-token
236

237
[private]
238
repository = https://private-pypi.company.com/simple/
239
username = company-user
240
password = company-token
241
```
242

243
### Per-Project Index Authentication
244

245
```toml { .api }
246
# pyproject.toml
247
[tool.uv]
248
index = "https://pypi.org/simple/"
249
extra-index-urls = [
250
    "https://test.pypi.org/simple/",
251
    "https://private.company.com/simple/",
252
]
253

254
# Authentication will use stored credentials
255
```
256

257
## Authentication Workflow
258

259
### Initial Setup
260

261
```bash
262
# 1. Generate API token on PyPI
263
# Visit: https://pypi.org/manage/account/token/
264

265
# 2. Login with token
266
uv auth login --token pypi-your-token-here
267

268
# 3. Test authentication
269
uv publish --repository testpypi dist/test-package-1.0.0.tar.gz
270
```
271

272
### CI/CD Integration
273

274
```bash { .api }
275
# GitHub Actions
276
env:
277
  UV_PUBLISH_TOKEN: ${{ secrets.PYPI_TOKEN }}
278

279
# GitLab CI
280
variables:
281
  UV_PUBLISH_TOKEN: $PYPI_TOKEN
282

283
# Jenkins
284
withCredentials([string(credentialsId: 'pypi-token', variable: 'UV_PUBLISH_TOKEN')]) {
285
    sh 'uv publish'
286
}
287
```
288

289
### Multiple Index Management
290

291
```bash
292
# Setup multiple indexes
293
uv auth login pypi --token pypi-token
294
uv auth login testpypi --token testpypi-token
295
uv auth login https://private.company.com --username user --password pass
296

297
# Publish to specific index
298
uv publish --repository pypi
299
uv publish --repository testpypi
300
uv publish --repository-url https://private.company.com/simple/
301
```
302

303
## Security Best Practices
304

305
### Token Management
306
- Use scoped tokens with minimal necessary permissions
307
- Rotate tokens regularly
308
- Store tokens in secure credential managers
309
- Never commit tokens to version control
310

311
### Access Control
312
- Use separate tokens for different purposes
313
- Limit token scope to specific projects when possible
314
- Monitor token usage for unauthorized access
315
- Revoke compromised tokens immediately
316

317
### Environment Security
318
- Use environment variables in CI/CD
319
- Encrypt sensitive configuration files
320
- Limit credential file permissions (600)
321
- Regular security audits of stored credentials
322

323
## Troubleshooting Authentication
324

325
### Common Issues
326

327
#### Authentication failures:
328
```bash
329
# Check stored credentials
330
uv auth token
331

332
# Re-authenticate
333
uv auth logout
334
uv auth login --token new-token
335

336
# Test with verbose output
337
uv publish --verbose
338
```
339

340
#### Keyring issues:
341
```bash
342
# Disable keyring temporarily
343
uv auth login --keyring-provider disabled
344

345
# Check keyring availability
346
python -c "import keyring; print(keyring.get_keyring())"
347
```
348

349
#### Token format errors:
350
```bash
351
# Verify token format
352
echo $UV_PUBLISH_TOKEN | head -c 20
353

354
# Use correct token prefix
355
# PyPI: pypi-<token>
356
# TestPyPI: testpypi-<token>
357
```
358

359
#### Permission errors:
360
```bash
361
# Check credential directory permissions
362
ls -la "$(uv auth dir)"
363

364
# Fix permissions
365
chmod 700 "$(uv auth dir)"
366
chmod 600 "$(uv auth dir)"/*
367
```