Skip to main content

Storage and backups

Back up the store before an upgrade. It holds prepared facts, people, settings, review decisions and run history. Losing a preview is a download; losing your decisions is a different problem.

What to keep​

DataDefault locationKeep it?
Store~/.immich-memories/store.db, or your PostgreSQL schemaYes
Config~/.immich-memories/config.yaml and deployment .env/SecretsYes
Saved-credential encryption keyIMMICH_MEMORIES_SECRET_KEYYes, with the store backup
Session signing keyIMMICH_MEMORIES_STORAGE_SECRET or .storage_secretKeep to preserve logins
Local films and run artifactsoutput.directoryKeep films you have not delivered elsewhere
Model weightsConfig/models volumeKeep to avoid downloading again
Thumbnails and downloaded clipscache.directoryDisposable

In Docker, the named config volume contains the store and config; ./output contains films. In Kubernetes, those are the cache and output PVCs. Keep SQLite on local disk, with one writer host. Database options cover PostgreSQL and shared installations.

Back up​

Python:

immich-memories store backup

Docker:

docker compose exec immich-memories immich-memories store backup
docker compose cp immich-memories:/home/immich/.immich-memories/backups ./backups

Kubernetes:

kubectl exec -n immich-memories deploy/immich-memories -c immich-memories -- immich-memories store backup
kubectl cp -n immich-memories <pod>:/home/immich/.immich-memories/backups ./backups -c immich-memories

Backups can run while the app is up. Copy them off the host. Keep each .db or .dump together with its .manifest.json; restore requires both. Save the encryption key separately and securely. PostgreSQL needs pg_dump on PATH, at least as new as the server; the image includes it.

Restore​

Stop the UI, timers and workers first. --force replaces an existing store: use the backup you intend and keep a copy of the current state. Restore with the release that made the backup when rolling back. A corrupt or truncated backup is caught before anything is replaced: the existing store stays as it was and the command exits with an error.

Python, after stopping the app:

immich-memories store restore --from /path/to/store.db --force
immich-memories preflight

Docker, with backup and manifest on the same mounted volume:

docker compose stop immich-memories
docker compose run --rm immich-memories immich-memories store restore \
--from /home/immich/.immich-memories/backups/store.db --force
docker compose up -d
docker compose exec immich-memories immich-memories preflight

Kubernetes restore job​

Suspend installed CronJobs first and record which were active. Wait for any running scheduled Job to finish, then scale the Deployment down and wait for its pod to release the PVC:

kubectl get -n immich-memories cronjob -l app.kubernetes.io/name=immich-memories
kubectl patch -n immich-memories cronjob immich-memories-auto -p '{"spec":{"suspend":true}}'
kubectl patch -n immich-memories cronjob immich-memories-monthly -p '{"spec":{"suspend":true}}'
kubectl scale -n immich-memories deploy/immich-memories --replicas=0
kubectl wait -n immich-memories --for=delete pod -l 'app.kubernetes.io/name=immich-memories,!job-name,!batch.kubernetes.io/job-name' --timeout=120s

Save this as restore-job.yaml. Replace X.Y.Z with the release and store.db with the actual backup filename. For PostgreSQL, use its .dump and add the same database Secret as the Deployment.

apiVersion: batch/v1
kind: Job
metadata:
name: immich-memories-restore
namespace: immich-memories
spec:
backoffLimit: 0
template:
spec:
restartPolicy: Never
enableServiceLinks: false
securityContext:
runAsUser: 1000
runAsGroup: 1000
fsGroup: 1000
containers:
- name: restore
image: ghcr.io/sam-dumont/immich-memories:X.Y.Z
command: [immich-memories, store, restore]
args: [--from, /home/immich/.immich-memories/backups/store.db, --force]
envFrom:
- secretRef:
name: immich-memories-secrets
volumeMounts:
- name: data
mountPath: /home/immich/.immich-memories
volumes:
- name: data
persistentVolumeClaim:
claimName: immich-memories-cache
kubectl apply -f restore-job.yaml
kubectl wait -n immich-memories --for=condition=complete job/immich-memories-restore --timeout=300s
kubectl logs -n immich-memories job/immich-memories-restore

Only after a successful restore:

kubectl delete -n immich-memories job/immich-memories-restore
kubectl scale -n immich-memories deploy/immich-memories --replicas=1
kubectl exec -n immich-memories deploy/immich-memories -c immich-memories -- immich-memories preflight

Resume only CronJobs that were active before maintenance with spec.suspend=false. The selector excludes both current batch.kubernetes.io/job-name and legacy job-name labels added by the Job controller, so Job and CronJob pods do not block the Deployment wait. It also works with the Terraform Deployment.

A SQLite backup restores to SQLite; a PostgreSQL backup to PostgreSQL. To change backend, restore first, then use store copy.

Caches​

The preview cache defaults to 30 GB, about 0.35 MB per picture a film's scope reaches, so a library of 90,000 fits. Video clips default to 10 GB, and so do prepared sources: the cut segments and photo clips a later render of the same selection reuses (advanced.analysis.prepared_source_cache_max_size_gb). Local-only films and failed deliveries remain on disk. After a confirmed upload to Immich, the local film and its run folder are removed, whether the run uploaded it or you did later with runs upload or Upload to Immich. runs storage lists what is kept; runs delete removes a run you no longer want.

cache:
video_cache_max_size_gb: 10
video_cache_max_age_days: 7
thumbnail_cache_max_size_mb: 30000

These are the defaults.

A preview averages about 315 KB: allow roughly 0.35 MB per candidate picture. Preparing 60,000 pictures needs about 21 GB for previews alone. Use the number of pictures in the requested period, including pictures preparation will later exclude from the film.

The thumbnail budget controls retention. Preparation protects its current previews until every analysis stage has read them, so that working set can exceed the budget. Lowering the budget does not make a large preparation fit on a small disk. Increasing it does not grow the volume.

Leave room for the store, job records, model runtime caches and downloaded video clips on the same volume: a 100 GiB data volume with a 50,000 MB thumbnail budget, for example, leaves space around a large preview set. Finished films are separate, at ~/Videos/Memories on Python or /app/output in the image.

Temporary working files​

Keep cache.directory and the output directory on mounted storage with free space. The app uses <cache.directory>/scratch for Python and child-process temporary files, including sampled video frames. The inference service uses <cache_dir>/scratch; the render worker uses <directory>/scratch. Startup sets Python's temporary directory and TMPDIR, TEMP and TMP together. An unusable scratch directory stops startup instead of falling back to /tmp.

Scratch directories must belong to the process user and allow no group or other access (0700). On Kubernetes, preserve that mode across PVC remounts with fsGroupChangePolicy: OnRootMismatch. See scratch permission recovery for an existing directory whose permissions were widened. Demucs and render jobs also keep their own working directories under their configured storage, including on the combined GPU worker.

Video and Live Photo preparation can keep sampled frames for many source clips at once. The size of a preparation batch does not cap that disk usage.

Scratch needs space beyond the preview and video cache budgets. Temporary files are removed when their work finishes. Each process works in a folder of its own inside the scratch and holds a lock on it while it runs, so a process that gets killed (out of memory, a pod restart) leaves an unlocked folder. The next start of the app, a CLI command or a worker removes those folders an hour after they last changed, and never touches one a live process still holds. You don't need to clean scratch by hand.

Past cut attempts live in <cache.directory>/editorial-runs and stay under cache.editorial_runs_max_size_gb (5 GB by default). The config reference lists what is trimmed first and what always stays.

Full disk during preparation​

A full disk can prevent both the work and its job-status update from being saved. The browser's progress may stay stale until space is available. After freeing space, reload the page; a job whose process has disappeared is marked interrupted.

Expand the full volume, or stop work and clear only disposable caches. Check free bytes and free inodes with df -h and df -i on the cache, output and temporary filesystems. For Kubernetes, verify the mounted filesystem has grown as well as the PVC's requested size. Keep the store and retry the same request: completed facts and usable cached previews are reused. Deleting the whole data volume loses those facts, settings and run history.

Clearing​

While the app is idle, use Settings > Caches > Clear. From a Python shell, these three folders alone are safe to delete:

rm -rf ~/.immich-memories/cache/video-cache
rm -rf ~/.immich-memories/cache/thumbnails
rm -rf ~/.immich-memories/cache/prepared-sources

In Docker, clear through Settings rather than deleting a similarly named host directory. Do not delete store.db or the whole data volume. Attempt directories also contain review/render inputs; removing the whole cache loses those artifacts even though banked facts remain in the store.

Moving an install​

Copy the config, encryption key and any films you need. Use store backup/store restore for the store, then run config test and preflight on the new host. Source settings may need new paths or addresses.