Immich is a self-hosted photo and video management platform that aims to give users control over their media without relying on proprietary cloud services. It addresses the common frustrations around data privacy, storage costs, and platform lock-in by providing a robust open-source alternative designed for homelab setups and personal servers.
What Immich does and how it is built
Immich is built to handle large volumes of photos and videos efficiently while supporting features typically found in commercial cloud services. It offers multi-user support, automatic backup from mobile devices, duplication detection, facial recognition, and metadata search. Users can organize their media with shared albums, support for raw formats, and even 360-degree image viewing.
At its core, Immich consists of a backend API, a database, and frontend clients for both mobile and web. The backend is implemented in TypeScript using the NestJS framework, which provides a modular and scalable server architecture. It integrates with PostgreSQL for storing metadata and uses Redis for caching and asynchronous task management.
Media files themselves are stored on user-defined storage backends, giving flexibility in how photos and videos are archived. The system supports local disk storage, network shares, or cloud storage providers, emphasizing user ownership and control.
Facial recognition and metadata extraction are handled through dedicated services that process uploaded media asynchronously. This design prevents blocking user requests and keeps the system responsive even under heavy load.
What stands out technically about Immich
One of Immich’s technical strengths lies in its architecture that balances feature richness with performance and scalability. Handling media at scale requires efficient processing pipelines and storage management, which Immich addresses through several design choices.
The backend leverages asynchronous processing extensively. For example, when new media is uploaded, the system queues jobs for generating thumbnails, extracting metadata, and running facial recognition separately. This queuing mechanism, backed by Redis, allows the system to scale these tasks independently and prevents slowdowns in the main API.
The choice of PostgreSQL for metadata storage is pragmatic. It supports complex queries needed for metadata search and user management while being well-understood and reliable. Redis caching further enhances read performance for frequent queries.
Immich’s codebase is surprisingly clean for a project of its scope. The use of TypeScript and NestJS conventions helps enforce modularity and testability. The frontend clients, also written in TypeScript with React Native and React, mirror this approach, providing consistent DX across platforms.
Tradeoffs are evident in the choice to rely on asynchronous tasks for heavy media processing. This design means that some features, like facial recognition results or duplicate detection, are not immediately available but appear after processing completes. This is a common tradeoff to maintain responsiveness but requires users to understand the delay.
Another limitation is the requirement for some infrastructure knowledge to set up the backend and storage properly. While the project is self-hosted and open source, users need a homelab or server environment with appropriate configuration skills.
Explore the project
The Immich repository is well organized with clear documentation in its README. The backend, mobile app, and web client are separated into distinct folders, making it easier to navigate.
Key resources include:
- The
backenddirectory contains the NestJS server code, including the API controllers, service layers, and job processing logic. - The
mobiledirectory hosts the React Native app source, which handles device backup and media upload. - The
webdirectory contains the React frontend for managing media through a browser. - Documentation covers setup, configuration options for storage backends, and usage guidance.
Reading through the backend’s job queue implementation and media processing modules reveals how the system manages asynchronous tasks effectively. The facial recognition service, for instance, uses third-party libraries wrapped in dedicated services to isolate complexity.
Exploring the API documentation is useful for understanding how clients interact with the backend, especially the endpoints related to media upload, user management, and search.
Verdict
Immich is a solid option for developers and hobbyists looking for a self-hosted media management solution that doesn’t compromise on features like facial recognition and metadata search. It’s especially relevant for those with some infrastructure experience who want to avoid proprietary clouds.
The project balances a rich feature set with a scalable architecture that handles media processing asynchronously to maintain performance. The tradeoff is a slightly delayed availability of some features and the need for careful setup.
For anyone running a homelab or personal server and wanting to maintain full control over their photos and videos, Immich is worth a close look. It doesn’t shy away from the complexities of media management, and the code is approachable enough to extend or customize if needed.
Related Articles
- Syncthing: secure, decentralized continuous file synchronization in Go — Syncthing is an open-source Go tool for continuous, secure, decentralized file synchronization across devices, emphasizi
- Hands-on with YOLOv5: A practical deep dive into Ultralytics’ PyTorch vision model — YOLOv5 by Ultralytics offers an accessible, fast, and accurate PyTorch-based computer vision toolkit for object detectio
- Hugging Face Transformers: a unified API for state-of-the-art AI models across modalities — Hugging Face Transformers offers a unified Python API to access over 1 million pretrained AI models for text, vision, an
- Pathway LLM App: unified pipelines for scalable retrieval-augmented generation and AI search — Pathway LLM App provides integrated pipelines for scalable RAG and AI search, combining vector and full-text indexing wi
- PinchTab: Token-efficient Chrome automation for AI agents with Go — PinchTab is a Go HTTP server enabling AI agents to control Chrome instances efficiently by extracting structured text, c
→ GitHub Repo: immich-app/immich ⭐ 98,648 · TypeScript