2. March 2026 | Michael Klissner

Immich is probably the best open-source alternative to Google Photos—and best of all, all your data stays with you! In this blog post, I’ll show you how to install Immich under Docker, including all the important settings for face recognition.

Note: This guide doesn’t cover Docker installation itself – I’m assuming Docker and Docker Compose are already running on your system.

If you haven’t installed Docker yet, you can find instructions here.: Install Docker Desktop for WINDOWS

📋 What is Immich?

Immich is a powerful, self-hosted photo and video backup solution with these highlights:

🔒 Privacy: Your photos stay on your server
📱 Automatic backup via iOS/Android app
🧠 AI features: Face recognition, object detection, smart search
👨‍👩‍👧‍👦 Multi-user capable including shared albums
🖼️ Supports RAW, HEIC, Live Photos and more

Video: Install Immich under Docker – The Perfect Google Photos Alternative

Language: 🇩🇪|🇬🇧
☝️ Use YouTube subtitles for all languages.

🚀 Installing Immich with Docker

1. Preparation

Create a directory for Immich and navigate into it:

bash

mkdir immich 
cd immich

2. Create the `.env` file

Create a file named .env with the following content:

env

# Immich - .env Configuration
# ====================================

# PATHS (MUST ADAPT!)
# Where should photos and videos be stored?
UPLOAD_LOCATION=/path/to/your/photos

# Where should the database be stored?
DB_DATA_LOCATION=/path/to/database

# Cache for Machine Learning (optional)
ML_CACHE=./immich-cache

# DATABASE (change password!)
DB_USERNAME=postgres
DB_PASSWORD=postgres   # ← CHANGE THIS! Letters/numbers only
DB_DATABASE_NAME=immich

# GENERAL
TZ=Europe/Berlin
IMMICH_VERSION=release

Important: Adjust the paths (UPLOAD_LOCATION and DB_DATA_LOCATION) to your system and change the DB_PASSWORD!

3. The `docker-compose.yml` file

Now comes the heart of the setup – the docker-compose.yml. I’ve kept it deliberately minimalist and clean, without unnecessary options:

yaml

name: immich

services:
  immich-server:
    container_name: immich_server
    image: ghcr.io/immich-app/immich-server:${IMMICH_VERSION:-release}
    volumes:
      - ${UPLOAD_LOCATION}:/usr/src/app/upload
      - /etc/localtime:/etc/localtime:ro
    env_file:
      - .env
    ports:
      - 2283:2283
    depends_on:
      - redis
      - database
    restart: always
    networks:
      - immich-network
    labels:
      - "com.centurylinklabs.watchtower.enable=true"

  # >>> FACE RECOGNITION - THIS IS WHERE THE MAGIC HAPPENS <<<
  # The Machine Learning container handles all AI functions:
  # - Face detection and recognition
  # - Object detection for smart search
  # - OCR (text recognition in images)
  # - Scene detection for videos
  immich-machine-learning:
    container_name: immich_machine_learning
    image: ghcr.io/immich-app/immich-machine-learning:${IMMICH_VERSION:-release}
    volumes:
      - ${ML_CACHE:-./ml-cache}:/cache
    environment:
      - MACHINE_LEARNING_WORKER_TIMEOUT=0      # Never shut down due to inactivity
      - MACHINE_LEARNING_CACHE_MODELS=true     # Keep models in RAM
      - MACHINE_LEARNING_MODEL_TTL=0           # Never unload models from cache
    env_file:
      - .env
    restart: always
    networks:
      - immich-network
    labels:
      - "com.centurylinklabs.watchtower.enable=true"
  # <<< END FACE RECOGNITION >>>

  redis:
    container_name: immich_redis
    image: docker.io/valkey/valkey:8-bookworm
    restart: always
    networks:
      - immich-network
    labels:
      - "com.centurylinklabs.watchtower.enable=true"

  database:
    container_name: immich_postgres
    image: ghcr.io/immich-app/postgres:14-vectorchord0.4.1-pgvectors0.2.0
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_USER: ${DB_USERNAME}
      POSTGRES_DB: ${DB_DATABASE_NAME}
    volumes:
      - ${DB_DATA_LOCATION}:/var/lib/postgresql/data
    restart: always
    networks:
      - immich-network
    labels:
      - "com.centurylinklabs.watchtower.enable=true"

networks:
  immich-network:
    driver: bridge

If you are interested in Watchtower to automatically update your Docker applications, you can find instructions here: Set up Watchtower for automatic updates

🔍 Understanding the Face Recognition Settings

The immich-machine-learning container is the core for all AI functions. These three environment variables ensure stable operation:

Please note that you still need to activate facial recognition in the settings:
Click on your profile picture in the top right corner -> Administration -> Apprentice Machine
“Facial recognition” and “Add faces” must both be turned on.

Variable	Value	Meaning
`MACHINE_LEARNING_WORKER_TIMEOUT`	`0`	The worker never shuts down due to inactivity. Otherwise, the container would stop after 5 minutes without jobs – and then face recognition would fail!
`MACHINE_LEARNING_CACHE_MODELS`	`true`	Loaded AI models (e.g., `buffalo_l` for faces) stay in RAM. This speeds up recognition enormously since they don’t need to be loaded from disk every time.
`MACHINE_LEARNING_MODEL_TTL`	`0`	Models are never removed from cache. This perfectly complements `CACHE_MODELS=true`.

Why are these settings so important?

Without this configuration, the following happens: The ML container shuts down after 5 minutes of inactivity (to save RAM). When new photos are uploaded or face recognition needs to start, the container is gone – jobs fail. With our settings, the ML container runs permanently and is immediately ready when needed.

4. Start Immich

bash

# Start containers
docker compose up -d

# Check if everything is running
docker compose ps

# View logs (optional)
docker compose logs -f

After starting, Immich is available at http://your-server-ip:2283. The first user to register automatically becomes admin.

📱 Connect Mobile Apps

Download the official Immich app from the App Store (iOS) or Play Store (Android). Enter the server URL as:

text

http://<YOUR-SERVER-IP>:2283/api

The app will then handle automatic backup of your photos and videos.

⚙️ After Installation: Testing Face Recognition

Upload some photos with people (via web or app)
Go to Administration → Jobs in the web UI
Start in sequence:
- “Thumbnails”
- “Face Detection”
- “Facial Recognition”

After some time (depending on the number of photos), recognized faces should appear in the People tab.

Tip: If no faces appear, check the logs: docker compose logs immich-machine-learning. Lines showing “Shutting down due to inactivity” indicate missing timeout settings.

🔄 Automatic Updates with Watchtower (Optional)

The docker-compose.yml already includes labels for Watchtower. If you install Watchtower separately, your Immich containers will update automatically. Since this is optional, you can find installation instructions in the Watchtower documentation.

📝 Conclusion

With this guide, you now have a fully functional, privacy-respecting Google Photos alternative up and running. The face recognition is stable and reliable thanks to the optimized settings.

Key points to remember: