How to Self-Host Immich: A Complete Guide

# self-hosted# immich# photo-management# google-photos-alternative# docker# privacy

Learn how to install and configure Immich, the open-source Google Photos alternative with native mobile apps, automatic backup, facial recognition, and AI-powered search - all on your own infrastructure.

How to Self-Host Immich: A Complete Guide

Immich has emerged as the definitive self-hosted replacement for Google Photos, offering native mobile apps with automatic backup, ML-powered search, and facial recognition; all running entirely on your own hardware. With 84,000+ GitHub stars, a thriving community of 74,000+ members across Discord and Reddit, and its October 2025 transition to stable status (v2.0), Immich delivers a privacy-respecting photo management experience that rivals commercial alternatives while keeping your memories under your complete control.

This guide walks you through deploying Immich from scratch, configuring advanced features like GPU acceleration and external libraries, and maintaining your installation long-term. Whether you're running a Raspberry Pi or a dedicated server with NVIDIA GPUs, you'll find the specific configurations needed for your setup.

Why choose Immich

Leading self-hosted photo solution

Immich stands apart from alternatives like PhotoPrism and LibrePhotos through its native iOS and Android apps with true background backup, a capability neither competitor offers natively. The mobile experience mirrors Google Photos closely, with automatic upload, timeline navigation, and offline support that "just works."

The machine learning capabilities deserve special attention. Immich uses CLIP-based semantic search that accepts natural language queries like "black cat on blue carpet in the morning", often outperforming Google Photos for specific searches. Face detection uses InsightFace models and consistently outperforms PhotoPrism's implementation. OCR support (added in v2.2.0) enables searching text within images.

FeatureImmichPhotoPrismLibrePhotos
Native mobile apps✅ iOS & Android❌ PWA only⚠️ Unofficial
Auto mobile backup✅ Background sync❌ Requires third-party❌ None
Facial recognition✅ Excellent⚠️ Poor✅ Excellent
CLIP search✅ Yes❌ No✅ Yes
Multi-user✅ Full support⚠️ Limited✅ Yes
LicenseAGPL-3.0AGPL-3.0 (paid tiers)MIT

The project releases updates approximately every 4-5 days, backed by FUTO for organizational support and funding. The AGPL-3.0 license ensures the codebase remains open source while preventing proprietary forks.

Server requirements and hardware recommendations

Immich runs surprisingly well on modest hardwre, though larger libraries benefit significantly from more resources. The minimum requirements are 2 CPU cores and 4GB RAM, but 6GB RAM and 4 cores provide a much smoother experience for libraries under 100,000 photos.

For libraries exceeding 500,000 assets, plan for 8+ cores, 32-64GB RAM, and consider GPU acceleration. A dedicated NVIDIA GPU (RTX 3060/4060 with 12GB VRAM) dramatically accelerates machine learning tasks and video transcoding.

Storage calculations should account for 10-20% overhead beyond your original files for thumbnails and transcoded videos. The database typically requires 1-3GB and must reside on local SSD storage...network shares are explicitly unsupported for PostgreSQL data and will cause corruption.

Operating system and NAS compatibility

Linux distributions (Ubuntu 22.04/24.04 LTS, Debian) provide the best experience. Windows users must run Docker via WSL2 with the database stored in Docker volumes rather than NTFS paths. All major NAS platforms work with platform-specific considerations:

  • Synology: Docker via Container Station or Portainer
  • QNAP: Container Station 3 with dedicated shared folders
  • Unraid: Docker Compose Manager plugin or Community Apps template
  • TrueNAS: Native community train application (v24.10.2.2+)

Docker Engine 25+ and Docker Compose V2 (the docker compose plugin syntax) are required. The legacy docker-compose command is deprecated and unsupported.

Installation

Pre-installation preparation

Before installation, verify your server meets these prerequisites:

Network configuration: Port 2283 must be accessible for the web interface. For external access, configure your domain's DNS A record pointing to your server's public IP. DDNS services like DuckDNS work if you lack a static IP. Crucially, Immich cannot run on a URL sub-path: it must be served at the root of a domain or subdomain (e.g., photos.example.com, not example.com/immich).

Reverse proxy requirements: All reverse proxies must forward the Host, X-Real-IP, X-Forwarded-Proto, and X-Forwarded-For headers. Configure upload limits of at least 50GB and timeouts of 600 seconds to handle large video uploads. WebSocket support is required for real-time features.

Storage preparation: Create dedicated directories for uploads and database storage. The upload location can reside on NAS or network storage, but database files require a local filesystem with Unix permissions (EXT4, ZFS, BTRFS, or XFS).

Docker Compose installation

The installation process takes approximately five minutes. Create a dedicated directory and download the official configuration files:

mkdir ./immich-app && cd ./immich-app
wget -O docker-compose.yml https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml
wget -O .env https://github.com/immich-app/immich/releases/latest/download/example.env

Edit the .env file with your configuration:

# Storage location for uploaded photos/videos
UPLOAD_LOCATION=/path/to/your/photos

# Database storage - MUST be local SSD, not network storage
DB_DATA_LOCATION=./postgres

# Set your timezone
TZ=America/New_York

# Version control - use 'release' for latest stable
IMMICH_VERSION=release

# CRITICAL: Change this to a strong random password
DB_PASSWORD=your-secure-password-here

# Database settings (usually unchanged)
DB_USERNAME=postgres
DB_DATABASE_NAME=immich

Generate a secure database password using pwgen -s 32 1 or similar. Use only alphanumeric characters to avoid parsing issues.

Start the containers:

docker compose up -d

The deployment creates four containers: immich_server (main application), immich_machine_learning (AI features), immich_postgres (database with VectorChord extension), and immich_redis (job queue via Valkey).

Access the web interface at http://your-server-ip:2283. The first user to register automatically becomes the administrator: complete this immediately after installation.

SSL and reverse proxy setup

Production deployments require HTTPS. Each reverse proxy option offers different trade-offs between simplicity and control.

Caddy configuration

Caddy provides the simplest setup with automatic Let's Encrypt certificates:

photos.example.com {
    reverse_proxy http://localhost:2283
}

Nginx configuration

For nginx, create a server block with appropriate upload limits and timeouts:

server {
    server_name photos.example.com;
    
    client_max_body_size 50000M;
    proxy_request_buffering off;
    client_body_buffer_size 1024k;
    
    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_read_timeout 600s;
    proxy_send_timeout 600s;
    send_timeout 600s;

    location / {
        proxy_pass http://localhost:2283;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Traefik configuration

For Traefik v3, add labels to the immich-server service in your docker-compose.yml:

labels:
  traefik.enable: true
  traefik.http.routers.immich.entrypoints: websecure
  traefik.http.routers.immich.rule: Host(`photos.example.com`)
  traefik.http.services.immich.loadbalancer.server.port: 2283

Configure appropriate timeouts in traefik.yaml to handle large uploads.

Configuration

Mobile apps and automatic backup

Install the Immich app from the Apple App Store, Google Play Store, or F-Droid. TestFlight provides access to beta releases on iOS.

On first launch, enter your server URL (https://photos.example.com for external access or http://192.168.1.x:2283 for local). Authenticate with your credentials created during web setup.

Configuring automatic bakcup requires navigating to the backup settings via the cloud icon in the app's top-right corner. Enable both foreground backup (triggers when opening the app) and background backup (periodic checks while app runs in background).

Background backup reliability depends heavily on your device's battery optimization settings. Android manufacturers aggressively kill background processes, consult dontkillmyapp.com for device-specific instructions. On iOS, enable Background App Refresh and avoid Low Power Mode during initial sync.

Selective backup lets you choose specific device albums rather than backing up everything. Enable "Show Storage indicator on asset tiles" in settings to visually distinguish synced versus local-only photos.

External libraries for existing photos

External libraries allow Immich to index photos stored outside its upload directory without moving or duplicating files. This preserves existing folder structures while enabling Immich's search and organization features.

First, mount your photo directories into the container by editing docker-compose.yml:

immich-server:
  volumes:
    - ${UPLOAD_LOCATION}:/data
    - /mnt/nas/photos:/mnt/nas/photos:ro
    - /home/user/pictures:/mnt/pictures:ro

The :ro flag creates read-only mounts, preventing accidental deletion through Immich's interface, recommended for irreplaceable originals.

Restart containers with docker compose up -d, then navigate to Administration → External Libraries → Create Library. Select the owner user, click Edit Import Paths, and add the container path (e.g., /mnt/nas/photos). Save and trigger a scan.

Exclusion patterns filter unwanted files during scans:

  • **/*.tif - exclude all TIFF files
  • **/Raw/** - exclude directories named "Raw"
  • **/@eaDir/** - exclude Synology system folders

Configure automatic periodic scanning in Administration → Settings → External Library to detect new files without manual intervention.

Hardware acceleration

GPU acceleration dramatically improves video transcoding and machine learning performance. Download the hardware acceleration configuration files:

wget -O hwaccel.transcoding.yml https://github.com/immich-app/immich/releases/latest/download/hwaccel.transcoding.yml
wget -O hwaccel.ml.yml https://github.com/immich-app/immich/releases/latest/download/hwaccel.ml.yml

NVIDIA GPU setup

Install the NVIDIA Container Toolkit and ensure driver version 545+ for CUDA 12.3 support. Modify docker-compose.yml:

immich-server:
  extends:
    file: hwaccel.transcoding.yml
    service: nvenc

immich-machine-learning:
  image: ghcr.io/immich-app/immich-machine-learning:${IMMICH_VERSION:-release}-cuda
  extends:
    file: hwaccel.ml.yml
    service: cuda

Enable NVENC in Administration → Video Transcoding Settings → Hardware Acceleration.

Intel QuickSync and VAAPI

For Intel integrated graphics or AMD GPUs, use VAAPI:

immich-server:
  extends:
    file: hwaccel.transcoding.yml
    service: vaapi
  devices:
    - /dev/dri:/dev/dri

Intel QuickSync VP9 encoding requires 9th generation or newer CPUs. Verify GPU access with ls -la /dev/dri inside the container.

Immich's machine learning features run automatically after installation, but tuning improves results significantly.

Navigate to Administration → Settings → Machine Learning Settings to adjust parameters. For facial recognition, the default buffalo_l model provides excellent accuracy; use buffalo_s on resource-constrained systems. The "Minimum Recognized Faces" setting determines how many detected faces are needed before Immich creates a named person: lower this to 1 if faces aren't appearing.

Maximum Recognition Distance afffects how strictly faces must match. Lower values (0.4) help distinguish similar-looking people like siblings; higher values (0.6) group more aggressively, reducing duplicates for the same person.

Access detected faces through the Explore page. Click a person grouping to assign a name, as named people become searchable throughout the library. Merge duplicate person entries via the menu in the person detail view.

Smart search uses CLIP models for natural language queries. The default ViT-B-32__openai model balances accuracy and resource usage. Larger models like ViT-H-14 improve search quality but require substantially more VRAM.

Maintenance

Backup strategies and disaster recovery

Database backups are critical; Immich stores all metadata, face data, and organizational information in PostgreSQL. The simplest backup method:

docker exec -t immich_postgres pg_dumpall --clean --if-exists --username=postgres | gzip > "/backup/immich-db-$(date +%Y%m%d).sql.gz"

Immich also creates automatic daily database dumps stored in UPLOAD_LOCATION/backups, keeping the last 14 by default. Configure this in Administration → Settings → Backup settings.

For photo library backups, prioritize these directories:

  • UPLOAD_LOCATION/upload or UPLOAD_LOCATION/library - original files
  • UPLOAD_LOCATION/profile - user profile images
  • UPLOAD_LOCATION/backups - database dumps

Thumbnails and transcoded videos (thumbs/ and encoded-video/) can be regenerated and may be excluded from backups to save space.

Restoration requires a fresh database. Stop containers, remove the postgres data directory, recreate containers, restore the dump, then start normally:

docker compose down -v
docker compose pull && docker compose create
docker start immich_postgres && sleep 10
gunzip --stdout backup.sql.gz | docker exec -i immich_postgres psql --username=postgres
docker compose up -d

Updating Immich safely

Updates follow a straightforward process:

cd /path/to/immich-app
docker compose pull && docker compose up -d
docker image prune -f

Always check release notes before updating: breaking changes occur regularly. Pin specific versions in .env (IMMICH_VERSION=v2.4.1) for controlled updates rather than always pulling latest.

Avoid Watchtower or similar auto-update tools given Immich's frequent breaking changes. Manual updates with backup verification provide much safer upgrades.

Alternative deployment methods

Deploying with Coolify

Coolify supports Immich as a one-click service, simplifying deployment for those already using the platform. Navigate to Services → Add Service, search for Immich, configure the required environment variables (UPLOAD_LOCATION, DB_DATA_LOCATION, DB_PASSWORD), and deploy. Coolify handles Docker Compose orchestration, SSL certificates via Let's Encrypt, and Traefik reverse proxy configuration automatically.

Advanced topics

Security hardening and authentication

OAuth/OIDC integration provides enterprise-grade authentication through providers like Authelia, Authentik, or Keycloak. Configure in Administration → Settings → OAuth Authentication with your provider's issuer URL, client ID, and secret. Critical: include app.immich:///oauth-callback in redirect URIs for mobile app compatibility.

API keys support scoped permissions (v1.138.0+) for integrations. Create keys in Account Settings → API Keys with minimal required scopes (asset.upload for backup tools, asset.view for read-only access).

For network security, never expose the database port publicly. Use Docker networks to isolate services, and consider adding Authelia or similar as an additional authentication layer in front of the reverse proxy. Generate strong database passwords and store credentials securely outside version control.

Troubleshooting common issues

Mobile app won't connect: Verify server URL format includes the protocol (http:// or https://). Test with local IP first to isolate reverse proxy issues. Clear app cache if problems persist. Ensure server and app versions match (major and minor).

Face recognition not detecting faces: Lower "Min Detection Score" to 0.5 in ML settings. Check ML container logs with docker compose logs -ft immich-machine-learning for model download failures. Re-run face detection jobs from Administration → Jobs.

Uploads failing: Increase reverse proxy upload limits to 50GB+. Cloudflare Tunnel users face a 100MB limit, use direct connections for large files. Verify disk space and directory permissions.

High memory usage: Reduce thumbnail generation concurrency in job settings. For very large libraries, consider running ML on a remote machine by deploying the ML container separately and configuring its URL in settings.

Database errors after updates: Check if VectorChord migration is required. Never downgrade below v1.133.0 after migrating to VectorChord.

Conclusion

Immich delivers a genuinely competitive alternative to Google Photos while keeping your data entirely under your control. The combination of polished mobile apps, powerful ML features, and active development makes it the clear choice for self-hosted photo management in 2026. Key success factors include proper database storage on local SSD, adequate hardware for your library size, and regular backups before updates. Start with the basic Docker Compose deployment, then layer in features like external libraries and hardware acceleration as your needs grow.