Paying a monthly subscription fee just to store thousands of blurry photos of parking tickets, half-eaten lunches, and slightly out-of-focus pets is a modern indignity. Big Tech cloud photo services offer slick interfaces, but hand over your private snapshots to proprietary ad networks, throttle uploads, and steadily increase storage prices.
Enter immich-app/immich, the open-source self-hosted photo and video backup solution that has rapidly become the crown jewel of homelab enthusiasts and privacy-conscious developers.
[ Client Apps ]
(Mobile / Web / CLI)
|
v
[ Reverse Proxy ]
|
+------------------+------------------+
| |
v v
[ Immich Server (NestJS) ] [ Immich ML Engine (Python) ]
| |
+---------+---------+ (ONNX / InsightFace / CLIP)
| | |
v v |
[ PostgreSQL ] [ Redis ] |
(+ pgvector) (Job Queues) |
^ |
+---------------- Vector Embeddings ------------+
What Is Immich?
Immich is a high-performance, self-hosted media management system engineered to replicate—and in many areas surpass—the speed and user experience of Google Photos and Apple Photos.
Unlike traditional NAS gallery software that feels like an uninspired PHP file explorer from 2004, Immich is built with modern, reactive components: NestJS on the backend, SvelteKit for the web client, Flutter for cross-platform mobile apps (iOS and Android), and a dedicated Python machine learning microservice running ONNX Runtime.
The platform processes raw photos, live photos, and 4K video clips, generates streaming-ready transcodes, and extracts spatial and visual embeddings without sending a single byte to an external server.
Key Architectural Highlights
Immich splits heavy-duty workloads across decoupled services orchestrated via Docker Compose:
- Vector Search with
pgvector: Rather than relying on rigid tagging, Immich uses multilingual CLIP (Contrastive Language–Image Pre-training) models to convert images into dense vector embeddings stored directly inside PostgreSQL via thepgvectorextension. A search query for "rusty bicycle in the rain" matches semantic image content locally. - Local Facial Recognition: Built-in InsightFace pipelines detect, align, and cluster faces across your entire photo library, grouping individuals into recognisable contacts without commercial APIs.
- Hardware-Accelerated Transcoding: Immich taps directly into Intel QuickSync, VA-API, Apple Silicon, or NVIDIA NVENC to compress heavy camera footage into snappy web-friendly H.264/H.265 formats on the fly.
- Native Background Mobile Sync: The Flutter mobile application supports real-time background asset syncing, background hash checking, and automatic album mapping.
Feature Matrix: Immich vs Conventional Alternatives
| Feature | Immich | Google Photos | Nextcloud (Memories) |
|---|---|---|---|
| Hosting Model | Self-hosted (Local/VPS) | Proprietary Cloud | Self-hosted (PHP stack) |
| Facial Recognition | Local (InsightFace / ONNX) | Cloud-based proprietary | Local (via python sidecar) |
| Semantic Search | Local CLIP embeddings | Proprietary server-side | Basic EXIF / external app |
| Database Engine | PostgreSQL + pgvector | Distributed internal | MariaDB / PostgreSQL |
| Mobile Experience | Native Flutter (smooth 120Hz) | Native iOS/Android | WebView / Native wrapper |
| Data Privacy | 100% user-retained | Ad-profiled / Scanned | 100% user-retained |
Deploying Immich with Docker Compose
Running Immich requires a clean directory structure with a dedicated docker-compose.yml and an environment file.
1. Directory Setup and Environment
Create a project directory and download the official configuration templates:
mkdir -p ~/immich && cd ~/immich
wget -O docker-compose.yml https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml
wget -O .env https://github.com/immich-app/immich/releases/latest/download/example.env
2. Configure Your .env
Edit the .env file to match your local storage mount paths and generate a secure database secret:
# Path where original media files will be stored
UPLOAD_LOCATION=/mnt/storage/photos
# Immich server release version
IMMICH_VERSION=release
# PostgreSQL configuration
DB_PASSWORD=supersecret_secure_password_here
DB_USERNAME=postgres
DB_DATABASE_NAME=immich
3. Start the Stack
Spin up the cluster:
docker compose up -d
Verify that the containers are healthy:
docker compose ps
Navigate to http://<your-server-ip>:2283 in your browser. You will be greeted by the initial administrator onboarding wizard.
Leveraging the Immich CLI for Bulk Imports
If you have ten years of photos sitting in folders on an external hard drive, uploading them through a web browser is an invitation to frustration. Immich provides an official Node-based CLI that calculates asset checksums locally and parallelises uploads.
Install the CLI globally:
npm install -g @immich/cli
Authenticate the CLI against your local instance:
immich login-key http://192.168.1.100:2283/api your_api_key_here
Run a dry run of your media catalogue, maintaining folder structures:
# Test import directory without transferring files
immich upload --dry-run -r /mnt/external_drive/Archive_2015_2024/
# Run the live multi-threaded import
immich upload --recursive --skip-hash-check /mnt/external_drive/Archive_2015_2024/
Tuning Machine Learning Workloads
By default, Immich pulls lightweight ONNX models to avoid melting low-powered SBCs like a Raspberry Pi. However, if you are running a server with dedicated graphics or a capable multicore x86 CPU, you can swap out the default CLIP model directly in the web UI under Administration > Machine Learning Settings:
Model Name: ViT-B-32__openai
Options:
- Batch Size: 8
- Concurrency: 2
- Min Score Threshold: 0.55
This improves natural language discovery. Searching for "boarding pass on wooden table" or "red vintage convertible" yields scarily precise results, running entirely within your home network on your own hardware.
Why Immich Is Leading the Self-Hosted Pack
Homelab forums and YouTube deployment channels routinely point out the exact friction point Immich solved: performance. While earlier self-hosted tools often stumbled on directories containing 80,000 unindexed RAW files, Immich decouples indexing from metadata parsing through Redis-backed background job queues.
If you want absolute sovereignty over your visual memories without forfeiting the modern computational perks of AI search, facial grouping, and instant mobile syncing, immich-app/immich is the benchmark open-source project to deploy today.