# Immich

> High-performance photo and video backup solution.

- Category: Storage & Backup
- Difficulty: intermediate
- Components: immich, postgres, redis, machine-learning
- Tags: immich, photos, videos, backup, ai
- Source: https://docker.recipes/storage/immich-v3

## Overview

Immich is a self-hosted photo and video management solution that provides a Google Photos-like experience with complete control over your data. Developed as a modern alternative to cloud photo services, Immich offers automatic mobile backup, AI-powered search capabilities, face recognition, and intuitive organization features without the privacy concerns or storage limitations of commercial platforms. This Docker stack combines Immich's main server with PostgreSQL using the pgvecto-rs extension for vector similarity searches, Redis for caching and session management, and a dedicated machine learning container that handles AI features like face recognition, object detection, and CLIP-based semantic search. The specialized PostgreSQL variant includes vector database capabilities essential for Immich's AI-powered search functionality, while Redis ensures fast response times for the web interface and mobile apps. This configuration is ideal for families, photography enthusiasts, and privacy-conscious users who want professional-grade photo management without relying on third-party cloud services, offering unlimited storage capacity limited only by your hardware while maintaining complete data ownership.

## Features

- Automatic mobile photo and video backup with iOS and Android apps
- AI-powered face recognition and clustering for easy person-based searching
- CLIP-based semantic search allowing natural language queries like 'beach sunset'
- Object and scene detection for automatic photo categorization and tagging
- Interactive world map view showing geotagged photos with location clustering
- Memories feature that creates automatic yearly recaps and highlights
- Live Photos support preserving motion from iPhone captures
- Multi-user support with individual libraries and shared album capabilities

## Use cases

- Family photo backup replacing Google Photos with unlimited storage capacity
- Photography enthusiast's personal archive with AI-powered organization and search
- Small business photo management for product catalogs or event documentation
- Travel photography collection with automatic location mapping and memories
- Multi-generational family sharing with secure album distribution to relatives
- Content creator's media library with semantic search for quick asset retrieval
- Privacy-focused individuals wanting complete control over personal photo data

## Prerequisites

- Minimum 4GB RAM recommended for smooth AI processing and face recognition
- At least 50GB free disk space for initial setup plus storage for your photo collection
- Port 2283 available for web interface access and mobile app connectivity
- Mobile device with iOS or Android for automatic photo backup functionality
- Basic understanding of environment variables for database password configuration
- Network storage or external drive mounted if managing large photo collections

## docker-compose.yml

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

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

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

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

volumes:
  immich_ml:
  immich_postgres:

networks:
  immich:
    driver: bridge
```

## .env

```bash
DB_PASSWORD=changeme
UPLOAD_LOCATION=./uploads
```

## Usage notes

- Docs: https://immich.app/docs/overview/introduction
- Access at http://localhost:2283 - create admin account on first visit
- Mobile apps: iOS and Android for automatic photo backup
- ML container handles face recognition, object detection, CLIP search
- Set UPLOAD_LOCATION to your photos directory path
- Google Photos alternative with excellent search and organization

## Troubleshooting

- Machine learning container consuming excessive memory: Reduce concurrent face recognition jobs in admin settings or allocate more RAM to the Docker host
- Mobile app fails to backup photos: Check that port 2283 is accessible from your network and verify the server URL in mobile app settings
- Face recognition not working on uploaded photos: Ensure the machine learning container is running and check job queue status in admin panel
- PostgreSQL connection errors on startup: Verify DB_PASSWORD environment variable matches between immich-server and postgres containers
- Slow photo loading and thumbnails: Increase Redis memory allocation or check if upload volume has sufficient disk space and proper permissions
- Upload location permission denied: Ensure the UPLOAD_LOCATION directory has proper read/write permissions for the container user

