Immich explained: architecture, backups, and the privacy limits of a self-hosted photo library

Immich is a self-hosted photo and video management system centered on mobile backup, browsing, search, sharing, and multiple users. At capture time, its repository had 108,332 stars, about 193 default-branch commits in 30 days, and a v3.0.3 release less than a week old. It is more than a gallery interface: mobile clients, media processing, metadata, search, and durable storage all move onto infrastructure controlled by the operator.

Common uses include automatic phone backup for a household, shared libraries, location and metadata search, public links, and centralized handling of RAW images, Live Photos, and video. The product also includes face clustering, CLIP search, duplicate handling, external libraries, and an API. Its appeal is a daily experience close to a hosted photo service while retaining infrastructure control. In exchange, the administrator owns uptime and recovery.

The official design is client-server. Android, iOS, web, and CLI clients call REST APIs; the server reaches PostgreSQL, Redis, the machine-learning service, and the filesystem through repository interfaces. Redis carries background work such as thumbnails, transcoding, and recognition. PostgreSQL stores users, asset paths, and metadata, while original and generated media live under the upload location. Face processing returns embeddings to the database, where nearest-neighbor search and clustering organize people.

The repository is primarily TypeScript. The web client uses SvelteKit, the mobile apps use Flutter, and the server depends on PostgreSQL and Redis, with machine-learning work separated into its own service. Docker Compose normally coordinates the containers and persistent volumes. The database records paths and relationships but does not rebuild all application state by scanning media folders. Treat the database and original files as one recoverable dataset, not independent copies.