Immich: a self-hosted Google Photos replacement on a NAS

Immich is the closest self-hosted equivalent to Google Photos: automatic phone backup, a fast timeline, face recognition, smart search, shared albums and a map view — all running on your own NAS, on your own disks, with no subscription and no third party scanning your family photos.

Published Nov 17, 2026 · Last updated Nov 18, 2026

That promise only holds if you set it up properly. Immich is not a single app; it is a small stack of containers that work together, and its database is as important as the photo files themselves. Lose the database and you lose albums, face names, sharing and favourites, even if every original file survives. This guide installs the stack the supported way, explains what each part does, and finishes with the two things people most often skip: a real backup, and a safe update routine.

What Immich actually runs

The current Docker Compose stack has four main services. The immich-server container provides the web interface, the API and background jobs, and listens on port 2283. The immich-machine-learning container handles face detection, face recognition and CLIP-based smart search — the feature that lets you search for “beach sunset” or “dog in snow” without tagging anything by hand. A Redis-compatible container (Valkey in recent releases) acts as the job queue between them. Finally, a PostgreSQL database with vector search extensions stores all metadata and the embeddings that make smart search and face matching work. That is why you must use the database image Immich specifies, not a plain Postgres image you happen to have.

Diagram of phones uploading photos to Immich on a NAS, with machine learning and database containers
How Immich fits together: phones upload to the server, machine learning indexes faces and content, and Postgres stores the metadata.

What you need

Step-by-step installation

  1. Create the folders. Make a folder for Immich, with a subfolder for uploads and a separate local folder for database data. Note the full paths; you will put them in the .env file as UPLOAD_LOCATION and DB_DATA_LOCATION.
  2. Download the official compose and env files into that folder, and pin a version. Set IMMICH_VERSION to a specific release rather than a floating tag, so an overnight restart never silently upgrades you.
  3. Set a strong database password in the .env file, and set your time zone. Keep this file private — it contains the only database credential.
  4. Start the stack with docker compose up -d, then watch the logs. The first start creates the database schema and downloads machine-learning models, so give it several minutes before assuming it is stuck.
  5. Open the web interface at http://your-nas-address:2283 and create the first account. That first account is the administrator. Use a long, unique password and store it in a password manager.
  6. Create accounts for each person in the household instead of sharing one login. Each user gets their own library and timeline, and you can then share albums between accounts — and optionally enable partner sharing so two people see one combined library.
  7. Install the Immich mobile app (iOS or Android), sign in to your server address, and turn on automatic backup. Choose which albums to back up, whether uploads may use mobile data, and whether backup runs only while charging if battery matters to you.
  8. Do a small test first. Take ten photos, confirm they appear in the timeline with the right dates and locations, then check they exist as files in the upload location. Only then start a bulk import.
  9. Import an existing library carefully. If your photos already live in folders on the NAS, add them as an External Library instead of re-uploading: mount the folder read-only into the server container, then create the library under Administration › External Libraries and scan it. Immich indexes those files in place without moving or duplicating them. For a Google Photos export, use the project’s recommended import tooling for Takeout files so dates and albums survive the move.
  10. Set up remote access safely. Do not port-forward port 2283 to the internet. Use a VPN-style connection such as Tailscale, or a properly configured HTTPS reverse proxy, so logins and uploads stay encrypted and the admin interface is not exposed to scanners.

A concrete configuration example

You normally keep the official compose file untouched and customise the .env file beside it. A typical .env looks like this:

# .env — keep this file private, it holds the database password
IMMICH_VERSION=v3.4.1
UPLOAD_LOCATION=/volume1/immich/library
DB_DATA_LOCATION=/volume1/docker/immich/postgres
DB_PASSWORD=use-a-long-random-password-here
DB_USERNAME=postgres
DB_DATABASE_NAME=immich
TZ=Etc/UTC

The version shown, v3.4.1, was the current release when this guide was last updated — check Immich's GitHub releases page and set IMMICH_VERSION to the newest release listed there. Keep it pinned to one specific release rather than a floating tag: Immich changes substantially across major versions, so always read the release notes before raising the pin, and back up (next section) before you upgrade.

To add an external library, you add one read-only volume line to the immich-server service in the compose file, recreate the container, and then create the library in the admin interface pointing at that internal path:

    volumes:
      - ${UPLOAD_LOCATION}:/data
      - /volume1/photos-archive:/mnt/archive:ro

The :ro matters. Read-only means Immich can index and display those photos but can never move, rename or delete your only copy while you are still deciding how you want the archive organised. Remember, though, that files in an external library are managed by you, not by Immich — they are not uploads the app controls. If you move, rename or delete the source files on the NAS yourself, the library entries break or the photos vanish from Immich. The read-only mount protects the archive from Immich; only your own care protects it from changes made outside Immich.

Backup diagram showing Immich library and database backed up together to an external drive and off-site storage
A useful Immich backup copies both the photo files and a database dump — one without the other is only half a backup.

Backups: files plus database, together

Immich writes scheduled database backups into the library’s backup folder, and you should also take your own. A complete backup has three parts: the original photo and video files, a dump of the Postgres database, and a copy of your .env and compose files so you can recreate the exact stack. Test the restore once on a spare machine or a second stack with different ports. A backup you have never restored is a hope, not a backup. Keep at least one copy off the NAS itself, because theft, fire and a failed RAID controller do not care that the files were “backed up” to the same box.

Backing up and restoring the database, step by step

Because the database half is the one people fumble, here is the explicit procedure. From the folder holding your compose file, dump the whole database to a single SQL file:

docker compose exec -T database pg_dumpall -c -U postgres > immich-dump.sql

Store immich-dump.sql with the photo backup set — ideally in the copy that lives off the NAS. To restore, install a fresh stack using the same Immich version that produced the dump, let the database container start, stop the server and machine-learning containers, and import the dump:

docker compose exec -T database psql -U postgres < immich-dump.sql

Then start the rest of the stack and sign in — your accounts, albums and face names come back with the dump. The version consistency matters: restore into the same release that created the dump, and only upgrade afterwards. A dump restored into a much older or newer stack can fail its schema migrations and leave you debugging instead of restored.

Common mistakes and troubleshooting

The stack starts, then the database container loops or exits

Usually the database data folder is on a network share, has the wrong ownership, or a plain Postgres image was substituted for the image Immich specifies with its vector extensions. Move DB_DATA_LOCATION to local storage, check the logs of the database container first — not the server — and compare your compose file against the official one for your version.

Faces and smart search never finish

The first scan of a large library can take days on a small CPU, and that is normal. Check the Jobs page in the admin interface: if jobs are progressing, leave it alone and let it run overnight. If they are stuck at zero, the machine-learning container is usually unhealthy, out of memory, or unreachable from the server container. Its logs will say which.

Phone uploads stall on iOS

iOS restricts background work aggressively. Open the app periodically during a large first backup, keep the phone on Wi-Fi and charging, and expect the initial upload to be a foreground task. Android is more forgiving, but battery-optimisation settings can also pause uploads until you exempt the app.

An update broke something

Immich moves fast and some releases include breaking changes that require a specific upgrade step. Read the release notes before every update, back up first, and never let anything auto-update this stack. If a new version fails, your pinned previous version plus the pre-update database dump is the way back.

Official documentation and references

Frequently asked questions

Can Immich replace Google Photos completely?

For backup, timeline browsing, search, face recognition and sharing, yes — those are its core features. What you take on yourself is the operations work Google used to do: disk failures, backups, updates and remote access are now your job. Most people find that a fair trade for keeping originals at full quality under their own control.

Should I upload my old folders or use an external library?

Upload (or use the import tooling) for photos you want Immich to manage long-term, including phone backups. Use an external library for a large, already-organised archive you do not want duplicated or moved. You can run both at once: managed uploads for new photos, read-only external libraries for the historical archive.

How much storage do I need?

Add it up in parts rather than with a single multiplier. Start with your original photo and video library. Add thumbnails and other generated assets — Immich keeps several derived sizes of every photo. Add transcoded video versions if you enable transcoding; for large video libraries they can rival the originals. Then add a growth allowance for the photos you have not taken yet. Count backup capacity separately: a backup needs roughly the library plus a database dump again, and a backup that lives on the same NAS is not protection against losing the NAS itself — keep at least one copy elsewhere.

Library feeling slow? Turn on the GPU: Immich hardware acceleration.