# Immich — High-Performance Self-Hosted Photo & Video Management

> Immich is an open-source Google Photos alternative with auto-backup, AI-powered search, face recognition, and mobile apps — self-hosted for complete privacy.

## Install

Save the content below to `.claude/skills/` or append to your `CLAUDE.md`:

## Quick Use

```bash
mkdir immich && cd immich
curl -o docker-compose.yml https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml
curl -o .env https://github.com/immich-app/immich/releases/latest/download/example.env
docker compose up -d
```

Open `http://localhost:2283` — create your admin account, then install the mobile app to start backing up photos.

## Intro

**Immich** is a high-performance, self-hosted photo and video management solution designed as a direct alternative to Google Photos. Built with NestJS, SvelteKit, and Flutter, it provides automatic mobile backup, AI-powered search, facial recognition, shared albums, and a beautiful timeline view — all running on your own hardware.

With 97.5K+ GitHub stars and AGPL-3.0 license, Immich is the most popular self-hosted photo solution, growing at an incredible pace due to its polished UX that rivals commercial services.

## What Immich Does

Immich provides a complete photo management experience:

- **Auto Backup**: Automatic photo/video backup from iOS and Android with background upload
- **Timeline View**: Chronological photo timeline with year/month navigation and memory flashbacks
- **AI Search**: Search photos by describing content ("dog on beach", "birthday cake", "sunset")
- **Face Recognition**: Automatic face detection and grouping, name your people for easy filtering
- **Shared Albums**: Create shared albums with family/friends, with activity feeds and comments
- **Map View**: View photos on a world map based on GPS metadata
- **Video Support**: Full video playback including RAW video formats and live photos
- **Multi-user**: Multiple accounts with separate libraries and shared spaces
- **External Libraries**: Mount existing photo directories without moving files

## Architecture

```
┌─────────────┐     ┌──────────────┐     ┌──────────────┐
│ Mobile App  │────▶│  Immich      │────▶│  PostgreSQL  │
│ (Flutter)   │     │  Server      │     │  + pgvector  │
├─────────────┤     │  (NestJS)    │     └──────────────┘
│ Web App     │     └──────┬───────┘
│ (SvelteKit) │            │         ┌──────────────┐
└─────────────┘     ┌──────┴───────┐ │  Redis       │
                    │ ML Service   │ │  (Job Queue) │
                    │ (Python/ONNX)│ └──────────────┘
                    └──────────────┘
```

## Self-Hosting

### Docker Compose (Official)

```yaml
services:
  immich-server:
    image: ghcr.io/immich-app/immich-server:release
    volumes:
      - ${UPLOAD_LOCATION}:/usr/src/app/upload
    environment:
      DB_URL: postgresql://immich:immich@database:5432/immich
      REDIS_HOSTNAME: redis
    depends_on:
      - redis
      - database
    ports:
      - "2283:2283"

  immich-machine-learning:
    image: ghcr.io/immich-app/immich-machine-learning:release
    volumes:
      - model-cache:/cache

  redis:
    image: redis:7-alpine

  database:
    image: tensorchord/pgvecto-rs:pg16-v0.2.0
    environment:
      POSTGRES_PASSWORD: immich
      POSTGRES_USER: immich
      POSTGRES_DB: immich
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:
  model-cache:
```

### Hardware Requirements

| Users | Photos | RAM | Storage | CPU |
|-------|--------|-----|---------|-----|
| 1-2 | <50K | 4GB | Photo size + 20% | 2 cores |
| Family | 50-200K | 8GB | Photo size + 20% | 4 cores |
| Power user | 200K+ | 16GB+ | Photo size + 20% | 4+ cores |

## Key Features

### AI-Powered Search (CLIP)

```
Search: "red car in parking lot" → finds matching photos
Search: "people hiking in mountains" → finds outdoor group shots
Search: "document with text" → finds screenshots and documents
```

The ML service uses CLIP models for semantic image search, running entirely offline on your server.

### Face Recognition

- Automatic face detection in all uploaded photos
- Cluster similar faces together
- Name people and filter your library by person
- Merge duplicate face clusters
- Hide specific faces from view

### Memory Flashbacks

Like Google Photos' "On this day" feature:
- Daily notifications of photos from the same date in previous years
- Animated memory slideshows
- Shared memories with family members

### Mobile App Features

- Background auto-backup (even when app is closed)
- Wi-Fi only backup option
- Selective album backup
- Partner sharing (see each other's photos)
- Offline photo access

## Immich vs Alternatives

| Feature | Immich | Google Photos | Synology Photos | PhotoPrism |
|---------|--------|--------------|-----------------|------------|
| Open Source | Yes (AGPL-3.0) | No | No | Yes (AGPL) |
| Self-hosted | Yes | No | NAS only | Yes |
| Mobile backup | Yes | Yes | Yes | Manual |
| AI search | CLIP (offline) | Google AI | Limited | TensorFlow |
| Face recognition | Yes | Yes | Yes | Yes |
| Map view | Yes | Yes | Yes | Yes |
| Mobile app | iOS + Android | iOS + Android | iOS + Android | PWA only |
| Storage | Unlimited | 15GB free | NAS capacity | Unlimited |

## FAQ

**Q: Do I need a GPU?**
A: No. The ML service runs on CPU via ONNX Runtime; a 4-core processor delivers a good search and face-recognition experience. A GPU accelerates processing but isn't required.

**Q: Can I migrate from Google Photos?**
A: Yes. Use Google Takeout to export photos, then bulk upload via immich-cli. Metadata (date, GPS, descriptions) is preserved. The community also maintains dedicated migration tools.

**Q: Is original photo quality preserved?**
A: Yes. Immich stores original files without compression or modification of your photos and videos. RAW formats (CR2, NEF, ARW, etc.) are supported.

## Source & Thanks

- GitHub: [immich-app/immich](https://github.com/immich-app/immich) — 97.5K+ ⭐ | AGPL-3.0
- Website: [immich.app](https://immich.app)

---
Source: https://tokrepo.com/en/workflows/immich-high-performance-self-hosted-photo-video-management-78d81c64
Author: AI Open Source