Cache Management
Cache Directory Locations
Yazi uses caching to speed up preview generation, especially for images. There are two cache modes:
| Mode | Location | Behavior |
|---|---|---|
| System cache (default) | Linux: $XDG_CACHE_HOME/yazi (~/.cache/yazi) | Auto-cleared on reboot (tmpfs) |
| Persistent cache | Configurable via cache_dir | Survives reboots; manually managed |
Persistent Cache Configuration
Set a persistent cache directory in yazi.toml:
[cache]
cache_dir = "/home/user/.cache/yazi-persistent"
This is useful if you want previews to remain cached across reboots (common on systems where /tmp is cleared).
Clearing the Cache
# Clear all cached data
yazi --clear-cache
This removes all generated preview thumbnails and cache artifacts. Yazi will regenerate them on next access.
Image Cache Settings
Image preview caching is controlled by several settings in yazi.toml:
[preview]
# Maximum image dimensions for cached previews
max_width = 600
max_height = 900
# Number of background preload workers
preload_workers = 4
| Setting | Impact |
|---|---|
max_width / max_height | Larger values produce higher-quality previews but consume more CPU (downscale) and storage (cache files) |
preload_workers | More workers preload images faster but increase CPU/memory usage on startup; set to 1 to minimize background impact |
Cache File Size Estimates
| Max Dimension | Avg Cache File Size |
|---|---|
| 300px | ~20–40 KB |
| 600px | ~60–120 KB |
| 1200px | ~200–500 KB |
Automatic Cache Cleanup
System cache directories on tmpfs are automatically cleared on reboot. For persistent caches, consider a cron job:
# Clean cache files older than 7 days
0 3 * * 0 find /path/to/cache_dir -type f -mtime +7 -delete
Preload Workers Strategy
- Fast SSDs: Higher
preload_workers(4–8) to populate the cache quickly when entering a directory - Slow HDDs / Network mounts: Lower
preload_workers(1–2) to avoid I/O contention - Set to
0: Disables background preloading entirely