Immich Storage Explained Where Your Photos Live and Why the Database Needs a Fast Local Disk
Containers are temporary — your photo folders are forever. The single most valuable Immich skill is knowing exactly which folder holds your originals, which holds the database, and which folders you may safely ignore. Get this right once and upgrades, migrations and backups all become boring.
✍️ Technical Anshu🐳 Docker / Linux Server⏱️ 6 minute read
🎥 The install video sets these folders up in minutes — this guide explains what each one is for
Every Immich horror story has the same root: someone treated the wrong folder as disposable. A deleted container is nothing. A deleted library folder is a lost family archive. The good news is the layout is simple once someone draws you the map — two locations, set in one file, decide everything.
The Immich storage layout — what lives where
UPLOAD_LOCATION — your actual library
upload/ and library/ — original photos and videosNEVER LOSE
thumbs/ — generated previewsREBUILDABLE
encoded-video/ — transcoded copiesREBUILDABLE
backups/ — automatic database dumpsPRECIOUS
DB_DATA_LOCATION — keep on a local SSD
postgres/ — the live databaseNEVER LOSE
👆 Example storage map. Originals and the database can never be recreated. Thumbnails and transcoded videos can — Immich will simply rebuild them.
1
UPLOAD_LOCATION — the Home of Your Originals
The UPLOAD_LOCATION value in your .env file points at the folder where Immich keeps the library itself:
upload/ and library/ — your original photos and videos, at full quality, exactly as the phone sent them. This is the crown jewel
thumbs/ — the small previews the timeline shows. Generated data: if deleted, Immich rebuilds them (slowly), and nothing real is lost
encoded-video/ — transcoded versions of videos for smooth playback. Also rebuildable
profile/ — user avatars and small assets. Tiny, but part of the library's identity
backups/ — Immich's own automatic database backups land here. Small files, enormous value
Practical sizing: your originals plus roughly 10-20 percent extra for the generated folders. Point this location at your biggest and most reliable storage — a large HDD or NAS volume is perfectly fine here, because plain files tolerate ordinary storage well.
2
DB_DATA_LOCATION — Small Folder, Absolute Rules
The database is the library's memory: albums, people, dates, places, search data. It is small compared to your photos, and it follows completely different rules:
Local disk only. Immich's documentation states plainly that network shares are not supported for the database. A live database writing over NFS or SMB is a documented corruption risk — this is the one rule with no exceptions
SSD strongly preferred. The database answers thousands of small queries as you scroll and search. On an SSD the interface feels instant; on a spinning disk it feels tired
Never edit it by hand. No browsing it, no 'cleaning' it, no moving it while containers are running. If it must move, stop the stack first with docker compose down, copy it, update the .env, and start again
3
The Volume Discipline That Keeps Photos Alive
Docker containers are rebuilt and replaced constantly — on every update, in fact. Your data survives because the compose file mounts real folders into the containers rather than storing anything inside them. Protect that separation:
Use real host paths in the .env file, and know where they physically are — run df -h on the folder and confirm which disk you are really trusting
Never run a 'cleanup' that prunes Docker volumes you do not recognise. An unrecognised volume may be your database
Changing a path in .env does not move any data — it just tells Immich to look somewhere new, usually somewhere empty. Move the files yourself, deliberately, with the stack stopped
Write down your two locations in your server notebook. In a panic at midnight, the person who needs this map is you
4
Moving Immich to a Bigger Disk Later
Libraries grow. When the disk fills, the migration is calm if you follow the order:
Stop everything: docker compose down
Copy the whole upload folder to the new disk — use a tool that preserves everything, and copy the database folder the same way if it is moving too
Update UPLOAD_LOCATION (and DB_DATA_LOCATION only if the database moved) in .env
Start with docker compose up -d and verify the timeline, a search, and an old album before deleting anything from the old disk
Keep the old copy untouched for a few days. Storage migrations are exactly where impatient deletions cause permanent losses
🔴 The one-sentence version: originals and database — never lose, never hand-edit; thumbnails and transcoded video — rebuildable. And the database never, ever lives on a network share.
🎥 Watch the Complete Process in the Video
Watch the install in the video to see these two locations being set — the .env step is where this whole guide happens.
Can my photos live on a NAS network share while the server runs elsewhere?
The photo files can — plain media files tolerate network storage reasonably well, and many people mount their library that way. The database cannot: the official documentation says network shares are not supported for it, and live database files on network storage are a real corruption risk. Keep DB_DATA_LOCATION on a disk inside the server itself.
Immich says my disk is full but the folder looks small. What else grows?
Usually the generated folders: thumbs and encoded-video quietly add 10-20 percent on top of your originals, and the automatic database backups accumulate too. Check the size of each subfolder before assuming the originals exploded.
I deleted the thumbnails folder by mistake. Have I lost my photos?
No. Thumbnails are generated previews, not originals. Restart Immich and re-run the thumbnail generation job from Administration, Jobs. It will take time on a large library, but every preview comes back.
This guide is based on the Technical Anshu video linked above • Stuck on a step? Ask in the video comments — that is where answers come fastest 🙏