# Immich

> High performance self-hosted photo and video backup.

- Category: Media & Entertainment
- Difficulty: intermediate
- Components: immich-server, immich-ml, postgres, redis
- Tags: immich, photos, backup, google-photos
- Source: https://docker.recipes/media/immich

## Overview

Immich is a high-performance, self-hosted photo and video backup solution designed as a privacy-focused alternative to Google Photos. Built with a modern TypeScript and Dart stack, Immich provides automatic mobile backup capabilities with advanced machine learning features for face recognition, object detection, and intelligent search. The application has gained significant traction in the self-hosting community for its rapid development pace and polished user experience that closely mirrors commercial cloud photo services.

This stack combines Immich's server component with a specialized machine learning service, PostgreSQL with vector extensions, and Redis for caching and job queuing. The immich-server handles the web interface and API endpoints, while immich-machine-learning processes photos for face recognition and CLIP-based semantic search using the pgvecto-rs PostgreSQL extension for efficient vector similarity operations. Redis manages background job queues for thumbnail generation, metadata extraction, and ML processing tasks.

This configuration is ideal for families wanting to centralize photo storage, privacy-conscious users migrating from Google Photos, and tech enthusiasts running home labs. The stack provides enterprise-grade photo management with features like multi-user support, album sharing, and geotagged photo mapping, while maintaining complete control over your data. The automatic mobile backup functionality makes it particularly valuable for households with multiple smartphones generating hundreds of photos monthly.

## Features

- Automatic mobile backup from iOS and Android apps with background sync
- Face recognition and grouping powered by machine learning models
- CLIP-based semantic search allowing natural language photo queries
- Live Photos support preserving motion and audio from iPhone captures
- Interactive map view displaying geotagged photos by location
- Memories feature creating automatic slideshows and yearly recaps
- External library integration for importing existing NAS photo collections
- Multi-user support with individual libraries and sharing permissions

## Use cases

- Family photo centralization replacing iCloud or Google Photos subscriptions
- Privacy-focused photo backup for users concerned about cloud data mining
- Home lab photo server with external library import from existing NAS storage
- Small business photo asset management with team sharing capabilities
- Photography enthusiast backup with high-resolution RAW file support
- Multi-generational family archives with face recognition across decades
- Travel photo organization with automatic geotagging and map visualization

## Prerequisites

- Minimum 4GB RAM recommended for ML processing and face recognition
- At least 100GB available storage space for photo uploads and database
- Port 2283 available for web interface access
- Mobile device with iOS or Android for automatic backup functionality
- Basic understanding of environment variables for database password configuration
- Network access from mobile devices to Docker host for backup uploads

## docker-compose.yml

```yaml
services:
  immich-server:
    image: ghcr.io/immich-app/immich-server:release
    container_name: immich-server
    restart: unless-stopped
    ports:
      - "2283:3001"
    environment:
      DB_HOSTNAME: database
      DB_USERNAME: postgres
      DB_PASSWORD: ${DB_PASSWORD}
      DB_DATABASE_NAME: immich
      REDIS_HOSTNAME: redis
    volumes:
      - immich_upload:/usr/src/app/upload
    depends_on:
      - redis
      - database

  immich-machine-learning:
    image: ghcr.io/immich-app/immich-machine-learning:release
    container_name: immich-ml
    restart: unless-stopped
    volumes:
      - immich_ml_cache:/cache

  redis:
    image: redis:7-alpine
    container_name: immich-redis
    restart: unless-stopped

  database:
    image: tensorchord/pgvecto-rs:pg14-v0.2.0
    container_name: immich-db
    restart: unless-stopped
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: immich
    volumes:
      - immich_db:/var/lib/postgresql/data

volumes:
  immich_upload:
  immich_ml_cache:
  immich_db:
```

## .env

```bash
DB_PASSWORD=changeme
```

## Usage notes

- Docs: https://immich.app/docs/overview/introduction
- Access at http://localhost:2283 - create admin on first visit
- Mobile apps (iOS/Android) for automatic photo backup
- ML container provides face recognition and CLIP search
- Uses pgvecto.rs for efficient vector similarity search
- External library support for existing NAS photo storage

## Troubleshooting

- Face recognition not working: Ensure immich-machine-learning container has adequate RAM allocation and check logs for model download failures
- Mobile app upload failures: Verify port 2283 is accessible from mobile network and check firewall rules on Docker host
- Database connection errors: Confirm DB_PASSWORD environment variable matches between immich-server and database containers
- ML processing stuck: Restart immich-machine-learning container and check available disk space in immich_ml_cache volume
- External library import fails: Verify file permissions and ensure immich-server container can read mounted photo directories
- Search not returning results: Wait for initial ML processing to complete and check pgvecto-rs extension is properly loaded in PostgreSQL

