Self-Hosting Immich: Private Photo Cloud

Your photos on self-hosted AI-powered backup

Page content

Immich is a revolutionary open-source, self-hosted photo and video management solution that gives you complete control over your memories. With features rivaling Google Photos - including AI-powered facial recognition, smart search, and automatic mobile backup - all while keeping your data private and secure on your own server.

Just as Personal Knowledge Management helps you organize and preserve your thoughts and information, Immich helps you organize and preserve your visual memories.

immich

What is Immich?

Immich is an open-source, self-hosted alternative to proprietary cloud photo services like Google Photos and iCloud. Built with modern technologies including TypeScript, PostgreSQL, and machine learning, Immich offers a feature-rich platform for backing up, organizing, and browsing your photo and video collection.

Key Features

Privacy-First Design: All your photos remain on your infrastructure. No third-party servers, no data mining, no privacy concerns. Your memories belong to you.

Automatic Mobile Backup: Native iOS and Android apps provide automatic background backup, similar to Google Photos. Your photos are secured moments after you take them.

AI-Powered Search: Leveraging machine learning models including CLIP and facial recognition, Immich enables semantic search. Search for “beach sunset,” “dog playing,” or specific people without manual tagging.

Face Recognition: Automatic detection and clustering of faces in your photos. Immich identifies people across your entire library, making it easy to find photos of specific individuals.

Modern Web Interface: Beautiful, responsive web interface for browsing, organizing, and sharing your photos from any device with a browser.

Multi-User Support: Create accounts for family members, each with their own private library. Share selected albums while maintaining privacy for personal photos.

Live Photo Support: Full support for iOS Live Photos and Android Motion Photos, preserving both the still image and video component.

Metadata Preservation: EXIF data including location, camera settings, and timestamps are preserved. View your photos on a map based on GPS coordinates.

External Library Support: Import existing photo libraries from external storage without copying files, saving disk space. Similar to how tools like Obsidian help manage and organize text-based knowledge, Immich provides powerful organization for visual media.

Why Self-Host Your Photos?

Complete Privacy Control

When you use commercial cloud services, your photos are stored on servers you don’t control. They may be analyzed for advertising, included in machine learning training data, or accessed by third parties. With Immich, your photos never leave your server unless you explicitly share them.

No Storage Limits

Cloud services charge based on storage tiers. With self-hosting, your only limit is your hardware capacity. A 10TB hard drive costs less than two years of premium cloud storage.

Cost Efficiency

After initial hardware investment, self-hosting has minimal ongoing costs. No monthly subscriptions, no surprise charges when you exceed storage limits.

Data Longevity

Cloud services can change terms, increase prices, or shut down entirely. Your self-hosted solution remains under your control indefinitely.

Learning Opportunity

Self-hosting Immich provides hands-on experience with Docker, reverse proxies, SSL certificates, database management, and server administration - valuable skills for any developer or DevOps professional.

Architecture Overview

Immich follows a microservices architecture with several components:

Immich Server: Main API server handling authentication, photo uploads, and database operations. Built with Node.js and TypeScript.

Immich Machine Learning: Separate Python service running TensorFlow models for facial recognition, object detection, and CLIP-based semantic search.

Immich Web: React-based web interface providing the user-facing application.

PostgreSQL: Relational database storing metadata, user information, and relationships between photos, people, and albums.

Redis: In-memory cache for session management and job queue coordination.

TypeSense (optional): Search engine for enhanced search capabilities and performance.

All components run as Docker containers, orchestrated with Docker Compose for simplified deployment and management.

Hardware Requirements

Minimum Specifications

  • CPU: 2 cores (x86_64 or ARM64)
  • RAM: 4GB (8GB recommended)
  • Storage: 10GB for application + photo library size
  • Network: 100 Mbps for local access
  • CPU: 4+ cores with good single-thread performance
  • RAM: 8-16GB (more for larger libraries)
  • Storage: SSD for database and application, HDD for photo storage
  • GPU: Optional but significantly accelerates ML tasks (NVIDIA with CUDA support)

Storage Considerations

Plan for approximately 1.15x your current photo library size to account for thumbnails and multiple resolutions. Use SSD storage for the PostgreSQL database for better performance.

For large libraries (100,000+ photos), consider:

  • NAS with RAID for data redundancy
  • Separate SSD for database
  • NVMe cache tier for frequently accessed photos

Installation Guide

Prerequisites

Before installing Immich, ensure you have:

  1. Linux Server: Ubuntu 22.04 LTS or Debian 12 recommended (see our comprehensive guide on How to Install Ubuntu 24.04 & useful tools for detailed setup instructions)
  2. Docker: Version 20.10 or newer
  3. Docker Compose: Version 2.0 or newer
  4. Domain Name: Optional but recommended for external access
  5. Reverse Proxy: Nginx or Caddy for SSL termination

Step-by-Step Installation

1. Install Docker and Docker Compose

# Update system packages
sudo apt update && sudo apt upgrade -y

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Add user to docker group
sudo usermod -aG docker $USER

# Install Docker Compose
sudo apt install docker-compose-plugin

For more details on curl commands and options, check out our cURL Cheatsheet. If you’re new to Docker, our Docker Cheatsheet provides essential commands and concepts.

2. Create Immich Directory Structure

# Create application directory
mkdir -p ~/immich/{library,database,machine-learning}
cd ~/immich

# Download docker-compose.yml
wget -O docker-compose.yml https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml

# Download environment template
wget -O .env https://github.com/immich-app/immich/releases/latest/download/example.env

If you’re new to bash scripting and command-line operations, our Bash Cheat Sheet provides helpful reference for common commands and directory operations.

3. Configure Environment Variables

Edit the .env file with your settings:

# Database Configuration
DB_PASSWORD=your_secure_password_here
DB_DATABASE_NAME=immich
DB_USERNAME=postgres

# Upload Location
UPLOAD_LOCATION=./library

# Machine Learning
MACHINE_LEARNING_ENABLED=true

# Timezone
TZ=America/New_York

# Public URL (for external access)
IMMICH_SERVER_URL=https://photos.yourdomain.com

Important: Generate a strong random password for DB_PASSWORD:

openssl rand -base64 32

4. Launch Immich

# Start all services
docker compose up -d

# Check service status
docker compose ps

# View logs
docker compose logs -f

These are just the basics - for a comprehensive reference of Docker Compose commands and operations, see our Docker Compose Cheatsheet.

5. Access Web Interface

Navigate to http://your-server-ip:2283 and create your admin account. This first account becomes the system administrator.

Setting Up External Access

For secure external access, configure a reverse proxy:

Nginx Configuration Example

server {
    listen 443 ssl http2;
    server_name photos.yourdomain.com;

    ssl_certificate /path/to/fullchain.pem;
    ssl_certificate_key /path/to/privkey.pem;

    client_max_body_size 50000M;

    location / {
        proxy_pass http://localhost:2283;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        
        proxy_read_timeout 600s;
        proxy_send_timeout 600s;
    }
}

Caddy Configuration Example (Simpler with automatic HTTPS)

photos.yourdomain.com {
    reverse_proxy localhost:2283
    
    @uploads {
        path /api/upload/*
    }
    request_body @uploads {
        max_size 50GB
    }
}

Mobile App Setup

iOS

  1. Download Immich from the App Store
  2. Enter your server URL (https://photos.yourdomain.com)
  3. Login with your credentials
  4. Enable automatic backup in Settings
  5. Choose which albums to backup (or all photos)
  6. Configure backup settings (WiFi-only, charging-only, etc.)

Android

  1. Download Immich from Google Play Store or F-Droid
  2. Enter server URL and credentials
  3. Grant photo/video access permissions
  4. Configure automatic backup settings
  5. Enable foreground service for reliable background backup

Backup Configuration Tips

  • WiFi Only: Enable to avoid mobile data charges
  • Charging Only: Prevent battery drain during large uploads
  • Include Videos: Videos consume significant storage and bandwidth
  • Background App Refresh: Enable on iOS for reliable syncing
  • Foreground Service: Enable on Android for consistent backup

Machine Learning Features

Face Recognition

Immich’s face recognition automatically detects and clusters faces across your library:

  1. Initial Processing: After upload, the ML service analyzes each photo for faces
  2. Face Clustering: Similar faces are grouped together
  3. Manual Assignment: Review clusters and assign names to people
  4. Continuous Learning: As you tag more photos, accuracy improves

Configuration:

# In docker-compose.yml, ML service environment
MACHINE_LEARNING_MODEL_CACHE=/cache
MACHINE_LEARNING_WORKERS=1  # Increase with more CPU cores

Immich uses CLIP (Contrastive Language-Image Pre-training) for semantic search:

  • Search for concepts without tags: “mountain landscape”, “birthday cake”, “red car”
  • Natural language queries understand context and relationships
  • Works across languages (though English typically yields best results)

GPU Acceleration

For significantly faster ML processing, enable GPU support:

NVIDIA GPU with CUDA

# In docker-compose.yml, ML service
services:
  immich-machine-learning:
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]

Ensure you have NVIDIA Container Toolkit installed:

distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | \
    sudo tee /etc/apt/sources.list.d/nvidia-docker.list

sudo apt update
sudo apt install -y nvidia-container-toolkit
sudo systemctl restart docker

Backup Strategies

While Immich backs up your photos from mobile devices, you should also backup Immich itself:

What to Backup

  1. Photo Library: The UPLOAD_LOCATION directory containing original photos
  2. Database: PostgreSQL database with metadata and relationships
  3. Configuration: .env file and docker-compose.yml

Database Backup

Automated Daily Backup Script

#!/bin/bash
# save as ~/immich/backup.sh

BACKUP_DIR=~/immich-backups
DATE=$(date +%Y%m%d_%H%M%S)

# Create backup directory
mkdir -p $BACKUP_DIR

# Backup PostgreSQL database
docker exec -t immich-postgres pg_dumpall -c -U postgres | \
    gzip > $BACKUP_DIR/immich_db_$DATE.sql.gz

# Keep only last 30 days of backups
find $BACKUP_DIR -name "immich_db_*.sql.gz" -mtime +30 -delete

echo "Backup completed: $BACKUP_DIR/immich_db_$DATE.sql.gz"

Make executable and schedule with cron:

chmod +x ~/immich/backup.sh
crontab -e
# Add line: 0 2 * * * ~/immich/backup.sh

For more information on bash scripting, automation, and cron jobs, refer to our comprehensive Bash Cheat Sheet.

Photo Library Backup

Your photo library should be backed up separately to another location:

Option 1: Rsync to NAS

rsync -avz --delete ~/immich/library/ nas:/backups/immich-photos/

Option 2: Cloud Backup (Encrypted)

# Using rclone with encryption
rclone sync ~/immich/library/ remote:immich-backup-encrypted/ --encrypt

Option 3: Local External Drive

rsync -avz --delete ~/immich/library/ /mnt/backup-drive/immich/

Maintenance and Updates

Regular Maintenance Tasks

Monitor Disk Space

# Check disk usage
df -h ~/immich/library
df -h ~/immich/database

# Check Docker volumes
docker system df

Monitor Performance

# View resource usage
docker stats

# Check specific service logs
docker compose logs immich-server --tail=100
docker compose logs immich-machine-learning --tail=100

Updating Immich

Immich updates frequently with new features and bug fixes. Update regularly:

cd ~/immich

# Backup database before updating
docker exec -t immich-postgres pg_dumpall -c -U postgres > backup_pre_update.sql

# Pull latest images
docker compose pull

# Stop and remove old containers
docker compose down

# Start with new images
docker compose up -d

# Check logs for any issues
docker compose logs -f

Database Maintenance

Periodic database maintenance ensures optimal performance:

# Vacuum and analyze database
docker exec -it immich-postgres psql -U postgres -d immich -c "VACUUM ANALYZE;"

# Check database size
docker exec -it immich-postgres psql -U postgres -d immich -c \
    "SELECT pg_size_pretty(pg_database_size('immich'));"

Performance Optimization

Storage Optimization

Use SSD for Database: PostgreSQL benefits significantly from SSD storage. Consider:

volumes:
  pgdata:
    driver: local
    driver_opts:
      type: none
      o: bind
      device: /mnt/ssd/immich-db

Separate Photo Storage: Keep large photo libraries on HDD while database remains on SSD:

UPLOAD_LOCATION=/mnt/hdd/immich-photos

Database Performance Tuning

For libraries with 50,000+ photos, tune PostgreSQL:

# In docker-compose.yml, postgres service environment
POSTGRES_SHARED_BUFFERS=256MB
POSTGRES_EFFECTIVE_CACHE_SIZE=1GB
POSTGRES_MAINTENANCE_WORK_MEM=64MB
POSTGRES_CHECKPOINT_COMPLETION_TARGET=0.9
POSTGRES_WAL_BUFFERS=16MB
POSTGRES_DEFAULT_STATISTICS_TARGET=100

Machine Learning Performance

Batch Processing: Process multiple photos simultaneously:

MACHINE_LEARNING_WORKERS=4  # Match CPU core count

GPU Acceleration: As mentioned earlier, GPU acceleration provides 5-10x speedup for ML tasks.

Security Best Practices

Authentication and Access Control

  1. Strong Passwords: Use password manager to generate and store complex passwords
  2. Two-Factor Authentication: Enable 2FA for admin account (if supported in your version)
  3. Regular Access Reviews: Periodically review user accounts and remove unused ones

Network Security

Reverse Proxy with SSL: Never expose Immich directly to internet without HTTPS:

# Use Let's Encrypt for free SSL certificates
sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d photos.yourdomain.com

Firewall Configuration:

# Allow only necessary ports
sudo ufw allow 22/tcp    # SSH
sudo ufw allow 80/tcp    # HTTP (redirect to HTTPS)
sudo ufw allow 443/tcp   # HTTPS
sudo ufw enable

VPN or Tailscale: For maximum security, access Immich through VPN:

  • Install Tailscale on your server and devices
  • Access via Tailscale IP (100.x.x.x)
  • No ports exposed to public internet

Container Security

Regular Updates: Keep Docker images updated to patch security vulnerabilities

Run Rootless: Configure Docker rootless mode for additional isolation

Resource Limits: Prevent DoS attacks by limiting container resources:

services:
  immich-server:
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 4G

Troubleshooting Common Issues

Upload Failures

Symptom: Photos fail to upload from mobile app

Solutions:

  • Check server disk space: df -h
  • Verify reverse proxy client_max_body_size setting
  • Check server logs: docker compose logs immich-server
  • Ensure mobile app has latest version

Machine Learning Not Processing

Symptom: Face recognition or search not working

Solutions:

  • Check ML container status: docker compose ps immich-machine-learning
  • View ML logs: docker compose logs immich-machine-learning
  • Restart ML service: docker compose restart immich-machine-learning
  • Verify model files downloaded: ls ~/immich/machine-learning/cache/

Database Connection Errors

Symptom: Web interface shows database connection errors

Solutions:

  • Verify PostgreSQL container running: docker compose ps immich-postgres
  • Check database logs: docker compose logs immich-postgres
  • Verify correct password in .env file
  • Test connection: docker exec -it immich-postgres psql -U postgres

Slow Performance

Symptom: Web interface or searches are slow

Solutions:

  • Check system resources: CPU, RAM, disk I/O
  • Run database vacuum: VACUUM ANALYZE;
  • Restart services: docker compose restart
  • Review PostgreSQL performance settings
  • Consider hardware upgrade (SSD, more RAM)

Mobile App Not Syncing

Symptom: Photos not backing up from mobile device

Solutions:

  • Verify background refresh enabled (iOS)
  • Enable foreground service (Android)
  • Check WiFi-only settings if on mobile data
  • Verify server URL accessible from mobile network
  • Review app permissions for photo access
  • Clear app cache and re-login

Migrating from Other Services

From Google Photos

Export Your Data:

  1. Go to Google Takeout (takeout.google.com)
  2. Select Google Photos
  3. Choose export format and size
  4. Download archives

Import to Immich:

  1. Extract downloaded archives
  2. Use Immich CLI tool or web upload
  3. Metadata is preserved from JSON sidecar files
# Using Immich CLI (install from releases)
immich upload --recursive /path/to/google-photos-export/

From iCloud Photos

Export:

  1. Visit iCloud.com
  2. Select photos to download
  3. Or use iCloud for Windows/Photos app export

Import: Similar to Google Photos, upload through web interface or CLI tool

From Local Storage

External Library Feature: Instead of uploading, point Immich to existing photo directory:

  1. Navigate to Administration > External Libraries
  2. Add library path (must be accessible from Docker container)
  3. Immich scans and indexes without copying files
  4. Saves significant disk space and time
# In docker-compose.yml, add volume mount
volumes:
  - /mnt/existing-photos:/mnt/external-library:ro

Community and Support

Official Resources

Contributing

Immich is open-source and welcomes contributions:

  • Bug Reports: Submit detailed issue reports on GitHub
  • Feature Requests: Discuss on Discord or GitHub Discussions
  • Code Contributions: Submit pull requests following contribution guidelines
  • Documentation: Improve docs for better user experience
  • Translations: Help localize Immich to your language

Alternative Tools

If Immich doesn’t meet your needs, consider:

  • PhotoPrism: More mature, feature-rich, different architecture
  • Piwigo: Traditional gallery-style interface
  • Nextcloud Photos: Part of larger Nextcloud ecosystem
  • Photoview: Simpler, lightweight alternative
  • LibrePhotos: Another Google Photos alternative with AI features

Conclusion

Self-hosting Immich provides a powerful, private alternative to commercial cloud photo services. While it requires initial technical setup and ongoing maintenance, the benefits of complete privacy control, no storage limits, and freedom from subscription fees make it worthwhile for many users.

The combination of automatic mobile backup, AI-powered search, face recognition, and modern interface creates an experience comparable to commercial offerings while keeping your data under your control. Whether you’re a privacy enthusiast, cost-conscious user with large photo libraries, or tech professional wanting hands-on infrastructure experience, Immich offers a compelling solution.

Start small with a home server or VPS, test with a subset of your photo library, and gradually migrate as you become comfortable with the system. The active community and frequent updates ensure Immich will continue improving and adding features.

Your memories are precious - take control of them with Immich.