Self-hosting guide

Immich at home

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.

The stack

Setup steps

  1. Prepare the drive. Create one folder on the external drive for the whole library, and note which drive letter Windows assigns it. That letter matters later — see the unplug/replug runbook below.
  2. Install Docker Desktop on the mini PC and make sure it starts when the PC boots.
  3. Install Immich with the official docker-compose file, pointing its upload location at the library folder on the external drive. Start it from the Immich folder with this command:
    Terminal — from the Immich folder
    docker compose up -d
  4. Create the admin account in the Immich web UI and let the first library scan finish. Face recognition and thumbnail jobs run in the background; a large library takes a while on first import.
  5. Install Tailscale on the PC and on each phone, signed into the same Tailscale account, and confirm the PC is reachable from the phone on the private network.
  6. Point the mobile app at the PC's Tailscale address, sign in, and turn on automatic backup. New photos then land in the library on their own.
  7. Health check: all Immich containers running (none stuck on "Restarting"), the web UI loads over Tailscale, the library photo count looks right, and a recent photo opens at full size.
Terminal — what a successful start looks like
 ✔ 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.

Immich — library view
Photos
Albums
Sharing
Map
Favourites

Illustration — the library view you should land on: your photos in the main grid, Sharing in the sidebar for partner photos.

Sharing with family (Partner Sharing)

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.

Browser — logged in as the person sharing
👤  Account▾
Account settings→
Partner Sharing+ Add partner
Administration— not here

Illustration — the path that is easy to miss: avatar menu → Account settings → Partner Sharing, in a browser session of the person doing the sharing.

Runbook: restarting the server

  1. Make sure the external drive is attached and showing the same drive letter it had before. If the letter changed, fix that first (see below) — do not start Immich against a missing path.
  2. Make sure Docker Desktop is running. If the PC was rebooted, Docker usually starts at login; if it didn't, launch it and wait for it to settle.
  3. From the Immich folder, run the start command. This starts (or restarts) every container.
    Terminal — from the Immich folder
    docker compose up -d
  4. Check container status with this command. Every container should settle to running/healthy. If the server container sits on "Restarting", read its logs before doing anything else — see the first issue below.
    Terminal — from the Immich folder
    docker compose ps
  5. Open the web UI over the Tailscale address and confirm the library loads and a photo opens. If the mobile app stops backing up, open it once while on the private network; backup resumes on its own.
Terminal — docker compose ps output
NAME               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.

Runbook: drive unplugged, then plugged back in

  1. Do not start Immich while the drive is missing. If the containers are running, stop them first with this command — a library path that vanishes under a running server only causes confusion.
    Terminal — from the Immich folder
    docker compose down
  2. Plug the drive back in and check the drive letter. Windows does not guarantee the same letter on replug, especially if another USB device was attached in between.
  3. If the letter changed, restore it before starting anything: open Disk Management, right-click the drive → Change Drive Letter and Paths → assign the original letter. Immich's upload location points at that letter, so the letter is part of the configuration.
    Run dialog — press Win + R
    diskmgmt.msc
  4. Verify the library folder is intact, including the hidden .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.
  5. Start the containers with the start command, confirm the server is healthy, and spot-check the library and a few thumbnails. If newly added files don't appear, trigger a library scan from the admin Jobs page.
    Terminal — from the Immich folder
    docker compose up -d
Disk Management
💽  System drive (C:)Healthy
💽  Photo library driveHealthy — check its letter
Change Drive Letter and Paths
Assign the following drive letter:[ original letter ▾ ]
OK

Illustration — if the replugged drive came back on a different letter, this dialog is where the original letter gets restored, before Immich starts.

Runbook: updating the server

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.

  1. Back up the database first. From the Immich folder, dump the database to a file in the same folder. Save it inside the Immich folder, not a system root, where the write can be denied.
    Terminal — from the Immich folder
    docker compose exec -T database pg_dump -U postgres immich > immich-db-backup.sql
  2. Check the latest release on Immich's GitHub releases page and note the exact version tag.
  3. Set the version in the .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.
  4. Pull the new images and restart. The pull should visibly download the new server image; if it finishes instantly with nothing downloaded, stop — the version did not change (see the last issue below).
    Terminal — from the Immich folder
    docker compose pull
    docker compose up -d
  5. Verify before calling it done: every container healthy (docker 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.
  6. After the update, confirm the library loads and a recent photo opens. If anything that talks to the server — a script, an automation — breaks, check the release notes for breaking changes before touching anything else. Keep the database backup until the new version has run cleanly for a day or two.

Issues found — and fixed

Server stuck on "Restarting" after cleaning up library folders

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.

Partner Sharing setting "not found"

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.

Library path broken after the drive came back on a different letter

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.

Update ran but the server still shows the old version

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.

Terminal — from the Immich folder
grep IMMICH_VERSION .env
docker compose config | grep image

If 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.

What it powers, and what's next

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.