A free, self-hosted photo library that lives on your own hardware — no cloud subscription, no storage meter, no one else's server holding your family photos.
Immich is a free, open-source alternative to Google Photos: it stores, organises and searches your photos, runs face recognition, and serves them through a web UI and a mobile app. This page documents a real home setup — a small Windows mini PC that stays on, an external hard drive holding the library, and Tailscale for private access from anywhere — along with the runbook for keeping it alive and every problem found and fixed so far. Nothing here is tied to any one household: no names, addresses, hostnames or drive letters, just the setup and the procedures.
Screen pictures on this page are illustrations of the layout to look for — sample photos and names in them are placeholders, not captures from this household.
docker compose up -d✔ Network immich_default Created ✔ Container immich_postgres Started ✔ Container immich_redis Started ✔ Container immich_server Started ✔ Container immich_worker Started
Illustration — every container should reach Started. If immich_server sticks on Restarting, see the first issue below before anything else.
Illustration — the library view you should land on: your photos in the main grid, Sharing in the sidebar for partner photos.
Immich's Partner Sharing is one-way: the person whose photos are shared adds the viewer as their partner, and the partner then sees those photos in their own app under Sharing. To share in both directions, each person repeats the steps for the other.
The setting is easy to miss: it is not in Administration → Settings, and it is not in the phone app. Open a desktop browser logged in as the person doing the sharing, go to the avatar menu → Account settings → Partner Sharing, and add the partner there.
Illustration — the path that is easy to miss: avatar menu → Account settings → Partner Sharing, in a browser session of the person doing the sharing.
docker compose up -ddocker compose psNAME STATUS immich_server Up (healthy) immich_postgres Up (healthy) immich_redis Up (healthy) immich_worker Up
Illustration — healthy looks like this. A server stuck on Restarting means stop and read the logs, not restart again.
docker compose downdiskmgmt.msc.immich marker files inside each library subfolder (upload, encoded-video, thumbs, and any others). If any marker is missing, restore it before starting — see the first issue below.docker compose up -dIllustration — if the replugged drive came back on a different letter, this dialog is where the original letter gets restored, before Immich starts.
Immich releases new versions often, and updating is just a version bump followed by a pull and a restart — but never skip the database backup first. A failed update with no backup is how a photo library becomes a recovery project.
docker compose exec -T database pg_dump -U postgres immich > immich-db-backup.sql.env file in the Immich folder: change the IMMICH_VERSION line to the new tag, for example IMMICH_VERSION=vX.Y.Z. Leave the database image line alone — only the Immich version changes.docker compose pull
docker compose up -ddocker compose ps), the new tag present in the image list (docker images), and the version shown in the web UI matching the new release. Only then update the mobile app from the app store.Symptom: after clearing files out of the library subfolders, the server container looped on "Restarting (1)" while the other containers stayed healthy. Its logs showed a missing-file error on startup, pointing at a path like /data/encoded-video/.immich, with the worker exiting code 1.
Cause: Immich's startup integrity check requires a hidden .immich marker file inside every subfolder of the upload location. Emptying those folders with a wildcard delete removed the markers along with the files.
Fix: copy a surviving marker (one subfolder usually still has its own) into each affected subfolder. The server recovered on its own within seconds of the markers being restored. Standing rule: never empty library subfolders with a wildcard — delete files selectively, and leave the marker files alone.
Symptom: the sharing option couldn't be found anywhere in the admin area or the phone app.
Cause: it lives in a different place than expected (see the sharing section above).
Fix: open a desktop browser logged in as the person doing the sharing, avatar menu → Account settings → Partner Sharing.
Symptom: Immich started but the library looked empty or errored, after the drive had been unplugged and replugged.
Cause: Windows assigned a different drive letter, so the configured upload path pointed at nothing.
Fix: reassign the original letter in Disk Management before starting the containers, as in the runbook above.
Symptom: the update steps were run — backup, version set, pull, restart — but the web UI still showed the previous version afterwards.
Cause: the edit to the .env file had not actually been saved, so the pull fetched nothing new: the image list showed only the old tags, and the containers were still running the old image.
Fix: confirm what is actually saved before pulling again — check the version line in .env and the images the compose file resolves to. On Windows, use findstr in place of grep.
grep IMMICH_VERSION .env
docker compose config | grep imageIf the old version is still there, re-edit and save the file, then pull again — this time the new image should visibly download — and restart.
With the server up, the library is available from any device on the private network, faces are recognised automatically, and a daily "this week in past years" photo memory runs off the same library. The honest gap in the setup today: the external drive is the only copy. The next improvement is a second, separate copy of the library — a backup drive or a second location — because a single drive is a single point of failure for a family photo archive. The other open item is verifying two-way Partner Sharing end to end once both directions are configured.
Immich itself moves fast, so treat this page as a field report, not a manual: for install commands and version-specific details, follow the official docs at immich.app, and Tailscale's at tailscale.com.