Immich Photo Server: The Ultimate Self-Hosted Guide for 2026

Reading time: ~15 minutes Audience: Homelab and self-hosting enthusiasts

What Is Immich?

Overview

Immich is a high-performance, self-hosted photo and video management platform designed as a replacement for Google Photos, iCloud, and Amazon Photos. It offers automatic mobile backup, facial recognition, duplicate detection, and a modern web interface. Unlike Nextcloud’s Photos app, Immich is purpose-built for media with a focus on speed, organization, and AI-powered features. It is open-source (MIT license) and actively developed with a large community.

A Brief History

Immich was created by Alex Tran in 2022 out of frustration with Big Tech photo services. The project quickly gained traction on GitHub and Hacker News due to its polished UI and aggressive feature roadmap. By 2024, Immich supported machine learning (CLIP-based search, facial recognition), hardware-accelerated transcoding, and OAuth login. It has become the default recommendation in the self-hosted community for photo management.

Why Use Immich in Your Homelab?

Privacy-First Photo Storage

Your photos are stored on your own hardware. There is no AI training on your data, no facial recognition by third parties, and no risk of account termination causing data loss. For parents, photographers, and privacy advocates, this is non-negotiable.

AI-Powered Search and Organization

Immich uses machine learning models to:

Recognize faces and group photos by person
Classify objects and scenes (beach, dog, sunset)
Generate natural language search (“photos of my dog at the beach”)
Detect duplicates across your library

These models run locally on your server. No data is sent to external APIs.

Automatic Mobile Backup

The Immich mobile app (iOS/Android) supports background upload, RAW file support, and burst photo handling. It can upload over Wi-Fi or cellular, with configurable quality settings (original or compressed). The app is native, fast, and supports offline viewing of recently accessed albums.

Installation

Prerequisites

A Linux server with 2+ vCPUs, 4 GB RAM (8 GB+ recommended for ML)
Docker and Docker Compose
An NVIDIA GPU (optional but strongly recommended for ML tasks)
At least 100 GB storage for photos and ML models

Method 1: Docker Compose (Recommended)

Immich is a multi-service application. The official Compose template includes the server, machine learning service, PostgreSQL, and Redis.

version: "3.8"

services:
  immich-server:
    container_name: immich_server
    image: ghcr.io/immich-app/immich-server:release
    command: ["start.sh", "immich"]
    volumes:
      - ${UPLOAD_LOCATION}:/usr/src/app/upload
    env_file:
      - .env
    ports:
      - 2283:3001
    depends_on:
      - redis
      - database
    restart: always

  immich-microservices:
    container_name: immich_microservices
    image: ghcr.io/immich-app/immich-server:release
    command: ["start.sh", "microservices"]
    volumes:
      - ${UPLOAD_LOCATION}:/usr/src/app/upload
    env_file:
      - .env
    depends_on:
      - redis
      - database
    restart: always

  immich-machine-learning:
    container_name: immich_machine_learning
    image: ghcr.io/immich-app/immich-machine-learning:release
    volumes:
      - model-cache:/cache
    env_file:
      - .env
    restart: always

  redis:
    container_name: immich_redis
    image: redis:7-alpine
    restart: always

  database:
    container_name: immich_postgres
    image: tensorchord/pgvecto-rs:pg14-v0.2.0
    env_file:
      - .env
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_USER: ${DB_USERNAME}
      POSTGRES_DB: ${DB_DATABASE_NAME}
    volumes:
      - pgdata:/var/lib/postgresql/data
    restart: always

volumes:
  pgdata:
  model-cache:

Create .env:

UPLOAD_LOCATION=./library
IMMICH_VERSION=release
DB_PASSWORD=***
DB_USERNAME=postgres
DB_DATABASE_NAME=immich

Deploy:

docker compose up -d

Access the web UI at http://your-server:2283. Create the first admin user.

Method 2: GPU-Accelerated Machine Learning

If you have an NVIDIA GPU, enable CUDA for faster face recognition and object classification:

  immich-machine-learning:
    container_name: immich_machine_learning
    image: ghcr.io/immich-app/immich-machine-learning:release-cuda
    volumes:
      - model-cache:/cache
    env_file:
      - .env
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]
    restart: always

Ensure the NVIDIA Container Toolkit is installed on the host.

Basic Setup and Configuration

Step 1: Configure the Mobile App

Download the Immich app from the App Store or Google Play
Enter your server URL: http://your-server:2283 (or https:// behind a reverse proxy)
Log in with your credentials
Enable Background Upload in settings
Set upload quality to Original (or Compressed to save space)

Step 2: Organize with Albums and Tags

The web UI supports albums, tags, and favorites. Create albums for events (“Vacation 2025”, “Baby’s First Year”). The AI will auto-suggest tags based on content. You can also manually tag photos for precise organization.

Step 3: Run the Machine Learning Pipeline

After uploading photos, the machine learning service processes them in the background. For a large library, this can take hours. Monitor progress in Administration → Jobs. You can manually trigger or pause jobs.

Advanced Features

External Libraries

Immich can ingest photos from existing directories without duplicating them. This is useful if you already have a NAS or a well-organized file structure.

In Administration → External Libraries, add a path
Set the scan schedule (e.g., daily at 2 AM)
Immich will read the files in-place and generate thumbnails

Storage Template

Immich stores files in a flat directory by default. You can configure a storage template to organize files by date:

{{y}}/{{y}}-{{M}}-{{d}}/{{filename}}

This makes it easier to browse the library directly on the filesystem.

Duplicate Detection

Immich runs a duplicate detection job that compares file hashes and perceptual hashes. You can review duplicates in the web UI and choose which to keep. This is invaluable when importing libraries from multiple sources.

OAuth and SSO

Immich supports OpenID Connect (OIDC) for single sign-on. Configure it with Authentik, Keycloak, or Authelia:

OAUTH_ENABLED=true
OAUTH_ISSUER_URL=https://authentik.example.com/application/o/immich/
OAUTH_CLIENT_ID=your-client-id
OAUTH_CLIENT_SECRET=your-client-secret
OAUTH_BUTTON_TEXT=Login with Authentik

Integrating with Your Homelab

Reverse Proxy and HTTPS

Expose Immich via a reverse proxy with valid HTTPS. The mobile app requires HTTPS for background upload on iOS.

labels:
  - "traefik.enable=true"
  - "traefik.http.routers.immich.rule=Host(`photos.yourdomain.com`)"
  - "traefik.http.routers.immich.tls.certresolver=letsencrypt"
  - "traefik.http.services.immich.loadbalancer.server.port=3001"

Backup Strategy

Back up both the PostgreSQL database and the upload directory:

# Backup database
docker exec immich_postgres pg_dump -U postgres immich > immich-backup.sql

# Backup library
tar czf immich-library-backup.tar.gz ./library

# Or use a backup container
docker run --rm \
  -v immich_postgres:/db:ro \
  -v ./library:/library:ro \
  -v /backup:/backup \
  offen/docker-volume-backup

Sync with rclone

For a 3-2-1 backup strategy, sync the library to cloud storage (S3, B2, Google Drive) with rclone:

rclone sync ./library remote:immich-backup --checksum --verbose

Alternatives to Consider

Nextcloud Photos

Nextcloud has a Photos app and a Memories app (a more advanced fork). Nextcloud is better if you want a unified platform (files, documents, photos). Immich is better if you want a dedicated, AI-powered photo experience. See our Nextcloud vs Immich comparison.

PhotoPrism

PhotoPrism is another AI-powered photo manager with a focus on privacy and archiving. It has a stronger emphasis on geo-tagging and map-based browsing. The UI is more “gallery-like” than Immich’s social feed style. PhotoPrism requires a commercial license for some features (high-resolution viewers, advanced AI).

LibrePhotos

LibrePhotos is an open-source photo manager with face recognition and auto-tagging. It is less polished than Immich but has a strong community. Good if you want a fully free alternative without the “release model” complexity.

Tool	Best For	AI	Mobile App	Cost
Immich	Modern replacement for Google Photos	Yes	Yes	Free
Nextcloud Photos	Unified file+photo platform	Limited	Yes	Free
PhotoPrism	Archival, geo-browsing	Yes	Web app	Free / Pro
LibrePhotos	Fully open, community-driven	Yes	No	Free

Frequently Asked Questions

How much storage does Immich need?

Immich stores originals and generates thumbnails, encoded videos, and ML embeddings. Budget 2–3x the size of your raw library. A 100 GB photo library will consume 200–300 GB on Immich.

Can I run Immich without a GPU?

Yes. The machine learning service falls back to CPU. Face recognition and object detection will be slower but functional. A modern CPU with AVX instructions is sufficient.

Is Immich stable for long-term use?

Immich is rapidly evolving. The core storage and API are stable, but the project occasionally introduces breaking changes. Always read the release notes before updating. Back up the database before major version bumps.

How does Immich handle RAW files?

Immich supports RAW formats (CR2, NEF, ARW, DNG). It generates JPEG thumbnails for web viewing and keeps the RAW for download. The mobile app can upload RAW files directly.

Conclusion

Summary

Immich is the best self-hosted photo management solution available today. It combines the convenience of Google Photos — automatic backup, AI search, and a polished mobile app — with the privacy and control of self-hosting. With Docker, it deploys in minutes. With GPU acceleration, the AI features are fast and responsive. For anyone with a growing photo library, Immich is the logical next step.

Next Steps

Install the mobile app and enable background upload
Import existing libraries via external library paths
Configure storage templates for date-based organization
Set up automated backups to offsite storage

Affiliate Opportunities

installation: hardware — NAS devices, large hard drives, NVIDIA GPUs
integration: tool — Authentik, Keycloak for OAuth
alternatives: tool — PhotoPrism commercial license

Internal Linking Strategy

installation → setup_guide: Docker Compose for beginners
integration → related_guide: Nextcloud vs Immich comparison
alternatives → comparison: Immich vs Google Photos

CTA

[comment] How many photos are in your library? Are you migrating from Google Photos or iCloud?
[newsletter] Subscribe for weekly self-hosted media and photo management guides.
[internal_link] Next: read our Nextcloud vs Immich deep comparison