0
# Cache Management
1

2
UV maintains a global cache for packages, metadata, and build artifacts to provide fast installations and reduce network usage. The cache system supports deduplication, automatic pruning, and manual management for optimal performance and disk usage.
3

4
## Capabilities
5

6
### Cache Cleaning
7

8
Remove cache entries to free disk space and resolve cache-related issues.
9

10
```bash { .api }
11
uv cache clean
12
uv clean                        # Legacy alias for cache clean
13
# Removes cache entries for packages and metadata
14
# Clears both package and metadata caches
15

16
# Options:
17
# PACKAGE...             # Clean specific packages only
18
# --all                  # Clean all cache entries (default)
19
# --dry-run             # Show what would be removed without removing
20
```
21

22
Usage examples:
23

24
```bash
25
# Clean entire cache
26
uv cache clean
27

28
# Clean specific packages
29
uv cache clean requests numpy
30

31
# Show what would be cleaned
32
uv cache clean --dry-run
33

34
# Clean with confirmation
35
uv cache clean --all
36
```
37

38
### Cache Pruning
39

40
Remove unreachable and orphaned cache objects while preserving recently used entries.
41

42
```bash { .api }
43
uv cache prune
44
# Removes unreachable objects from cache
45
# Preserves recently used packages and metadata
46

47
# Options:
48
# --ci                  # Use CI-appropriate pruning strategy
49
# --dry-run            # Show what would be pruned without removing
50
```
51

52
Usage examples:
53

54
```bash
55
# Prune unreachable cache objects
56
uv cache prune
57

58
# Show what would be pruned
59
uv cache prune --dry-run
60

61
# Use CI-friendly pruning
62
uv cache prune --ci
63
```
64

65
### Cache Directory Information
66

67
Display cache location and usage statistics for monitoring and troubleshooting.
68

69
```bash { .api }
70
uv cache dir
71
# Shows the cache directory path
72
# Location where UV stores cached data
73
```
74

75
Usage examples:
76

77
```bash
78
# Show cache directory
79
uv cache dir
80

81
# Show cache size
82
du -sh "$(uv cache dir)"
83

84
# List cache contents
85
ls -la "$(uv cache dir)"
86
```
87

88
## Cache Structure
89

90
UV organizes the cache into logical sections for efficient access and management:
91

92
```text { .api }
93
cache/
94
├── wheels/              # Built wheels for packages
95
│   ├── pypi/           # PyPI package wheels
96
│   ├── simple/         # Simple index wheels
97
│   └── git/            # Git repository wheels
98
├── built-wheels/       # Locally built wheels
99
├── downloads/          # Downloaded source distributions
100
├── metadata/           # Package metadata cache
101
│   ├── pypi/          # PyPI metadata
102
│   └── simple/        # Simple index metadata
103
├── builds/             # Build environments and artifacts
104
└── git/               # Git repository clones
105
    ├── db/            # Git database objects
106
    └── checkouts/     # Git working directories
107
```
108

109
## Cache Configuration
110

111
Configure cache behavior through UV settings and environment variables.
112

113
### Global Cache Configuration
114

115
```toml { .api }
116
[tool.uv]
117
cache-dir = "~/.cache/uv"           # Custom cache directory
118
no-cache = false                    # Disable cache usage
119
cache-keys = ["platform", "python"] # Cache key components
120

121
# Cache size limits
122
max-cache-size = "10GB"             # Maximum cache size
123
cache-retention = "30d"             # Cache retention period
124
```
125

126
### Environment Variables
127

128
```bash { .api }
129
UV_CACHE_DIR=/custom/cache/path     # Custom cache directory
130
UV_NO_CACHE=1                      # Disable cache usage
131
UV_LINK_MODE=copy                  # Cache linking mode (copy/hardlink/symlink)
132
```
133

134
### Per-Command Cache Control
135

136
```bash { .api }
137
# Global cache options (available for most commands):
138
--cache-dir DIR                     # Override cache directory
139
--no-cache                         # Disable cache for this operation
140
--refresh                          # Refresh cached data
141
--refresh-package PACKAGE          # Refresh specific package cache
142
```
143

144
## Cache Benefits
145

146
### Performance Improvements
147
- **Fast installations**: Reuse downloaded and built packages
148
- **Reduced network usage**: Cache packages and metadata locally
149
- **Parallel builds**: Cache enables concurrent package processing
150
- **Incremental updates**: Only download changed components
151

152
### Disk Space Efficiency
153
- **Deduplication**: Share identical files across cache entries
154
- **Compression**: Store cached data in compressed format when beneficial
155
- **Intelligent linking**: Use hardlinks and symlinks to save space
156
- **Automatic cleanup**: Remove unreachable cache entries
157

158
## Cache Strategies
159

160
### Linking Modes
161

162
UV supports different cache linking strategies:
163

164
```bash { .api }
165
# Hardlink mode (default, most efficient)
166
UV_LINK_MODE=hardlink
167

168
# Copy mode (safer, uses more space)
169
UV_LINK_MODE=copy
170

171
# Symlink mode (efficient, may have compatibility issues)
172
UV_LINK_MODE=symlink
173
```
174

175
### Cache Keys
176

177
UV generates cache keys based on multiple factors:
178

179
- **Platform**: Operating system and architecture
180
- **Python version**: Major.minor Python version
181
- **Package version**: Exact package version and hash
182
- **Dependencies**: Dependency tree hash
183
- **Build configuration**: Build settings and environment
184

185
## Cache Maintenance
186

187
### Automatic Maintenance
188

189
UV performs automatic cache maintenance:
190

191
- **Size-based cleanup**: Remove old entries when cache exceeds limits
192
- **Time-based cleanup**: Remove entries older than retention period
193
- **Access-based cleanup**: Remove least recently used entries
194
- **Integrity checks**: Verify cache entry integrity and remove corrupted data
195

196
### Manual Maintenance
197

198
Regular maintenance commands:
199

200
```bash
201
# Check cache size and usage
202
du -sh "$(uv cache dir)"
203
uv cache dir && find "$(uv cache dir)" -type f | wc -l
204

205
# Clean specific package types
206
uv cache clean --dry-run | grep wheels
207
uv cache clean requests urllib3 certifi
208

209
# Prune old cache entries
210
uv cache prune --dry-run
211
uv cache prune
212

213
# Complete cache rebuild
214
uv cache clean --all
215
```
216

217
### Cache Monitoring
218

219
Monitor cache performance and usage:
220

221
```bash { .api }
222
# Cache statistics
223
ls -la "$(uv cache dir)" | head -20
224

225
# Package-specific cache usage
226
find "$(uv cache dir)" -name "*requests*" -type f
227

228
# Cache age analysis
229
find "$(uv cache dir)" -type f -mtime +7  # Files older than 7 days
230

231
# Disk usage by cache component
232
du -sh "$(uv cache dir)"/*
233
```
234

235
## Multi-User Cache
236

237
UV supports shared cache configurations for teams and CI environments:
238

239
### Shared Cache Setup
240

241
```bash { .api }
242
# Set shared cache directory
243
export UV_CACHE_DIR=/shared/uv-cache
244

245
# Set appropriate permissions
246
mkdir -p /shared/uv-cache
247
chmod 775 /shared/uv-cache
248
chgrp developers /shared/uv-cache
249
```
250

251
### Cache Isolation
252

253
```bash { .api }
254
# User-specific cache
255
UV_CACHE_DIR=~/.cache/uv-$USER
256

257
# Project-specific cache
258
UV_CACHE_DIR=./.uv-cache
259

260
# Environment-specific cache
261
UV_CACHE_DIR=/tmp/uv-cache-$$
262
```
263

264
## CI/CD Cache Integration
265

266
Optimize CI/CD pipelines with cache management:
267

268
### GitHub Actions
269

270
```yaml { .api }
271
- name: Cache UV
272
  uses: actions/cache@v3
273
  with:
274
    path: ~/.cache/uv
275
    key: uv-${{ runner.os }}-${{ hashFiles('**/pyproject.toml') }}
276
    restore-keys: |
277
      uv-${{ runner.os }}-
278
```
279

280
### GitLab CI
281

282
```yaml { .api }
283
cache:
284
  key: uv-$CI_COMMIT_REF_SLUG
285
  paths:
286
    - .cache/uv/
287

288
before_script:
289
  - export UV_CACHE_DIR="$CI_PROJECT_DIR/.cache/uv"
290
```
291

292
### Docker Builds
293

294
```dockerfile { .api }
295
# Multi-stage build with cache
296
FROM python:3.12 as builder
297
ENV UV_CACHE_DIR=/opt/uv-cache
298
RUN pip install uv
299
COPY . /app
300
WORKDIR /app
301
RUN uv sync
302

303
# Production stage
304
FROM python:3.12-slim
305
COPY --from=builder /opt/uv-cache /opt/uv-cache
306
COPY --from=builder /app/.venv /app/.venv
307
```
308

309
## Troubleshooting Cache Issues
310

311
### Cache Corruption
312

313
```bash
314
# Verify cache integrity
315
uv cache prune --dry-run
316

317
# Clean corrupted entries
318
uv cache clean --dry-run
319
uv cache clean
320

321
# Complete cache reset
322
rm -rf "$(uv cache dir)"
323
uv cache dir  # Recreates cache directory
324
```
325

326
### Disk Space Issues
327

328
```bash
329
# Check cache size
330
du -sh "$(uv cache dir)"
331

332
# Clean large packages
333
du -sh "$(uv cache dir)"/* | sort -rh | head -10
334
uv cache clean large-package
335

336
# Aggressive cleanup
337
uv cache prune
338
uv cache clean --all
339
```
340

341
### Permission Issues
342

343
```bash
344
# Check cache permissions
345
ls -la "$(uv cache dir)"
346

347
# Fix permissions
348
chmod -R u+rw "$(uv cache dir)"
349

350
# Reset cache with correct permissions
351
rm -rf "$(uv cache dir)"
352
uv cache dir
353
```
354

355
### Network vs Cache Issues
356

357
```bash
358
# Force network refresh
359
uv pip install --refresh requests
360

361
# Disable cache temporarily
362
uv pip install --no-cache requests
363

364
# Compare with/without cache
365
time uv pip install --no-cache requests
366
time uv pip install requests
367
```
368

369
## Cache Security
370

371
### Security Considerations
372

373
- Cache contents are not encrypted by default
374
- Shared caches should use appropriate file permissions
375
- Network-sourced cache entries should be verified
376
- Regular cache cleanup prevents information leakage
377

378
### Best Practices
379

380
```bash
381
# Secure cache permissions
382
chmod 700 "$(uv cache dir)"
383

384
# Regular cleanup
385
uv cache prune --ci
386

387
# Cache isolation for sensitive projects
388
UV_CACHE_DIR=/secure/project-cache
389

390
# Audit cache contents
391
find "$(uv cache dir)" -type f -name "*.whl" | head -10
392
```