Immich: self-hosted photo and video library (Google Photos–class, AGPL-3)

Immich is a leading open-source option for: Google Photos–style backup, albums, and search on hardware you control. The immich-app/immich monorepo combines a server API, web UI, Flutter mobile apps, and a machine-learning stack for faces, objects, and CLIP-style search—aimed at people who will trade vendor convenience for ops responsibility.

Below is a concise overview, not a substitute for docs.immich.app.

Who should run Immich?

Immich is not “free Google Photos.” It is Google Photos–class UX with your uptime, your backups, and your security patches.

Common troubleshooting scenarios

Mobile backup stalls. Check TLS certificate validity, server URL reachability from cellular (not just Wi‑Fi), and background app refresh permissions on iOS. Immich logs on the server show upload queue depth—spikes after vacations are normal; persistent zero progress often means cert or DNS issues.

ML search returns nothing. Face and CLIP indexing runs asynchronously. Confirm the ML container is healthy, disk has space for embeddings, and you waited through initial backfill. Large libraries may need days on CPU-only hosts.

Database migration fails on upgrade. Stop writes, restore DB from pre-upgrade snapshot, read GitHub issues for the target release, and retry on a staging clone first. Never delete library/ when DB restore is the fix.

Slow web UI on NAS. Spinning rust for Postgres or thumbnail cache hurts; move hot paths to SSD or reduce concurrent ML jobs during peak browsing.

Partner sharing confusion. Shared albums and partner libraries have different permission models—read docs.immich.app for current behavior before onboarding non-technical family members.

TL;DR

Features that matter in production

From the public README / feature matrix:

• Mobile: auto-backup when opened, background backup, dedup, RAW, Live/Motion Photo, offline-friendly gallery patterns.
• Library: albums, shared albums, partner sharing, public links, archive, favorites, stacked photos, folder view.
• Discovery: timeline, global map, “memories” (on-this-day style).
• Search: metadata; object/scene; facial recognition and clustering; CLIP semantic search where ML indexing is enabled.
• Admin: user management and API keys are web-first in their table; mobile vs web parity for tags and some views varies—check the current matrix before promising stakeholders.

Why the architecture matters for capacity

Immich splits responsibilities like a modern cloud product, but you run every tier:

• Core API — auth, libraries, jobs, storage layout.
• Clients — web and mobile talk to the same API.
• Machine learning — heavy inference (faces, embeddings, detection) off the interactive path.

Planning is not only disk: large libraries need CPU (or GPU, depending on how you run ML) for thumbnails, transcodes, and background ML queues—profile on your hardware.

Hardware sizing (rule of thumb)

Immich’s ML pipeline (faces, CLIP embeddings, object detection) is asynchronous—initial import of a large iPhone camera roll can take hours to days depending on hardware. Set expectations with stakeholders before flipping DNS.

Docker deployment path

Official docs at docs.immich.app/install/docker-compose remain canonical. Typical stack:

1. Clone or pin the release tag from immich-app/immich releases—do not run latest in production without a rollback plan.
2. Configure .env — set UPLOAD_LOCATION, database credentials, and public IMMICH_SERVER_URL for mobile clients.
3. Bring up Postgres, Redis, server, ML, and microservices per the compose file version you pinned.
4. Create admin user via web UI on first launch.
5. Install mobile apps (iOS/Android) and point them at your HTTPS endpoint—TLS is non-negotiable for background backup on modern OSes.
6. Run a test restore from backup before trusting irreplaceable photos to the stack.

# Illustrative — follow upstream compose for exact service names
git clone https://github.com/immich-app/immich.git
cd immich
git checkout v1.x.x   # pin a release tag
docker compose -f docker/docker-compose.yml up -d

Immich vs Google Photos vs PhotoPrism

Choose Immich when mobile backup + gallery UX matter as much as privacy. PhotoPrism remains strong for web-centric archives and DAM-style workflows; many homelabbers run both for different libraries.

Backup: the 3-2-1 rule (non-optional)

The upstream README is explicit: photos are irreplaceable. A workable homelab plan:

1. 3 copies — live library on NAS, nightly rsync/restic to external USB, quarterly off-site copy (friend’s vault, S3 Glacier, Backblaze B2).
2. 2 media types — SSD/NAS + external HDD or cloud object storage.
3. 1 off-site — encrypted tarball or restic repo outside your home.

Snapshot Postgres (pg_dump or volume snapshots) with file storage—Immich metadata lives in the DB; files alone are not a restore.

Test restores quarterly. A backup you have never restored is a hypothesis.

Mobile backup workflow

1. Install Immich from App Store / Play Store.
2. Connect to your server URL (must be HTTPS with valid cert for reliable background sync).
3. Enable auto-backup for camera roll; exclude screenshots if desired.
4. Verify deduplication on a test album before enabling for the whole family.
5. Monitor server disk—mobile backup is write-heavy during vacations and holidays.

Partner sharing and shared albums work well for families; document who owns the server admin account and who can delete libraries.

AGPL-3 in practice

AGPL-3 can impose source-sharing obligations when you modify the app and let users interact over the network. Most home labs running upstream images unmodified have a different risk profile than hosting providers or white-label products. Get legal review before betting a business on a fork or a re-skinned multi-tenant Immich.

Upgrade and maintenance cadence

Immich ships frequently. A sane ops rhythm:

• Pin Docker image tags; read release notes before bumping.
• Backup DB + library immediately before upgrades.
• Stage upgrades on a clone volume when libraries exceed 500 GB.
• Subscribe to GitHub security advisories for the monorepo.

Breaking changes occasionally affect ML re-indexing—budget time for background jobs to catch up after major version jumps.

Security hardening

Self-hosting shifts security ownership to you—Immich does not replace WAF, IDS, or SOC monitoring.

FUTO and project governance

Immich’s public site references FUTO (futo.org) for sponsorship and merchandise. That funding context matters for long-term maintenance expectations—not for day-one install steps. Monitor project velocity on GitHub (contributors, release cadence) the same way you would any critical infra dependency.

Related on ExplainX

• Sim (Sim Studio): open-source agent workflows and self-hosted ops
• Hermes Agent: self-hosted Nous Research CLI + Telegram
• What is MCP? Model Context Protocol guide

Sources

• Site: immich.app
• Docs: docs.immich.app
• Repository: github.com/immich-app/immich
• Roadmap: immich.app/roadmap

Summary

Immich delivers Google Photos–class backup, search, and sharing on hardware you control—at the cost of ops, backups, and AGPL awareness. Pin releases, run 3-2-1 backups, size CPU for ML queues, and treat the docs as canonical for install and upgrade steps.

Start path: Docker compose from a pinned release → HTTPS reverse proxy → mobile apps pointed at your domain → test restore before migrating family libraries.

For a broader self-hosted stack map, see Sim Studio agent workflows and MCP for tool integration—Immich itself does not ship MCP, but homelab operators often run both photo libraries and agent infra on the same NAS.

Migration from Google Photos

There is no official one-click import from Google Takeout to Immich that preserves every album edge case. Practical migration:

1. Export via Google Takeout (original quality if storage allows).
2. Import into Immich via CLI or web upload in batches by year to throttle ML indexing.
3. Re-create shared albums manually; permissions do not map 1:1.
4. Keep Google subscription until verify Immich backup restore on a test device.

Expect weeks of background processing for large libraries—communicate to family before canceling Google.

Bottom line: Immich rewards operators who treat photos like production data—backups, pinned releases, and honest capacity planning—not casual Docker experiments.

Next steps: Read docs.immich.app/install, pin a release tag, schedule your first restore drill, then migrate a pilot album before moving the full family library off Google Photos entirely.

GitHub stars, release tags, and feature matrices change often. Treat this as May 5, 2026 context and verify versions before upgrades.