How to Configure Immich Cache and Temporary Storage
Configure Immich cache and temporary storage by first separating durable library state from generated derivatives, reusable model cache, and truly disposable container scratch data.
Thumbnails and encoded videos may feel like cache because Immich can regenerate them, but they are persistent working assets that can become large and expensive to rebuild. Model downloads have a different lifecycle, while logs and writable-layer scratch should not silently consume the boot disk. Assign storage by role, then test cleanup and restart behavior.
Classify Each Storage Role Before Moving It
Create an inventory with at least four classes: originals and required application state; generated thumbnails and previews; generated encoded videos; and model, log, or temporary runtime data. For each class, record current path, size, growth rate, backup policy, rebuild cost, and the service that writes it.
A user report of generated thumbnail and video growth demonstrates why thumbnails and encoded video need to be measured separately. Individual ratios are not universal, because media mix and processing settings change the amount produced.
Do not label a directory โcacheโ merely because deleting it frees space. If its loss causes days of regeneration, breaks active playback, or removes state your recovery plan expects to retain, it deserves an explicit persistent role even if the application can technically recreate it.
Place High-Churn Generated Data Where Latency and Endurance Fit
Thumbnails and previews serve interactive browsing and often involve many small reads, while encoded videos can consume much larger sequential capacity. A fast SSD can improve derivative-heavy activity, but only if moving that role removes the measured wait rather than creating another small volume that fills unexpectedly.
The ZimaSpace explanation of thumbnail storage growth provides the transferable storage lesson: active app storage can fill even when originals live elsewhere. Immich-specific paths differ, but the requirement to monitor the actual writable role is the same.
If bulk media stays on HDD or NAS storage while derivatives move to SSD, monitor both free-space floors and verify every mount after restart. A fast derivative tier is useful only when it is large enough for normal growth and its failure cannot be mistaken for loss of the authoritative originals.
Persist Model Cache Deliberately but Treat It as Rebuildable
Machine-learning models are downloaded or prepared for repeated inference and can consume meaningful storage. Persisting the model cache avoids unnecessary downloads and startup work, especially on slower links, but it should not be confused with the database or family originals in the recovery hierarchy.
A community discussion about Immich storage architecture illustrates why operators separate fast cache-like data from bulk photo storage. Use such layouts as examples only; verify the current paths and mounts in your own Compose definition before moving anything.
If the model cache is lost, the acceptable recovery is normally to recreate or redownload it, provided the service can reach the required source and has enough disk space. Document that behavior so a backup tool does not spend scarce offsite capacity protecting a large regenerable cache by accident.
Keep Writable Layers, Logs, and Scratch Space Bounded
Container writable layers should not become an undocumented home for persistent derivatives, temporary transcodes, or large logs. Inspect Docker disk usage and container mounts so every large growing path is either deliberately persisted or intentionally disposable. An unexplained writable-layer spike is a configuration symptom, not a cleanup target by default.
The 2026 Docker HQ workflow for safe Docker disk cleanup emphasizes auditing before pruning and protecting volumes that may contain databases. Apply that caution here: never run blanket cleanup commands on a production Immich host until the ownership of each volume and layer is known.
Set log rotation, keep scratch paths on storage with enough burst headroom, and monitor inode as well as byte usage when many small files are created. If a temporary path fills, the correct fix is to bound or relocate that role, not to delete unfamiliar directories until the application happens to start.
Validate Storage Changes With Restart, Rebuild, and Free-Space Tests
After changing paths, open old and recent assets, browse several albums, play a video, run one thumbnail or machine-learning job, and upload a controlled new file. Confirm that writes land on the intended devices and that the database still references readable media.
Restart the containers and then the host. A passing configuration remounts every role automatically, retains the expected derivatives and model cache, keeps scratch disposable, and reports enough free space on each active tier. Watch storage for a normal workload window to confirm growth appears where planned.
Rollback a path change if Immich creates duplicate directories, reports missing assets, or silently writes to the container layer because a mount failed. Escalate with mount maps, path sizes, ownership, filesystem free space, container disk usage, and the exact job that first wrote to the wrong location.
Recommended products
Support & Tips
More to Read
How to Optimize Immich Database Connections for Concurrent Containers
Do not raise max_connections first. Measure Immich sessions, total every container's demand, preserve admin headroom, and tune only the proven bottleneck.
How to Prevent Duplicate Jobs or Imports in Immich
Separate repeated jobs from duplicate assets. Use one canonical ingestion path, control retries and path changes, then test re-entry on a small cohort.
How to Repair Immich After Its Database Volume Fills Up
Never delete PostgreSQL WAL to free space. Stop Immich writes, preserve database state, add safe capacity, recover PostgreSQL, then prevent recurrence.
