Immich on a Pi 4: a photo library that survives the phone upgrade

Four containers, and what each one costs

The stack is a server, a Postgres database with the vector extensions, a Redis queue, and the machine learning worker. On a Pi, the ML worker is the one to think about: it spends about four seconds of CPU on every new photo for CLIP embeddings and face detection, which is fine for a phone upload of twenty photos and painful for a first import of forty thousand.

The first import is the hard part

Forty thousand photos with the ML worker enabled on a Pi 4 takes about two days of background work, during which the board is warm and everything else on it feels slow. Doing it in stages is far better: import with ML disabled, let thumbnails and metadata finish, then enable ML overnight and let it work through the library in batches.

The job concurrency setting is what makes this bearable. The defaults assume a server with cores to spare; setting the thumbnail and ML concurrency to 1 on a Pi keeps interactive use of the rest of the rack responsive.

docker exec -it immich-server immich-admin list-jobs
# then in the admin UI: Settings -> Job Settings -> Thumbnail Generation / Smart Search
# set concurrency to 1 and start the job manually rather than letting it queue

Why the database cannot be the stock Postgres image

Immich's smart search stores image embeddings as vectors and queries them by cosine distance. That needs the vectorchord and pgvecto.rs extensions, which are not in the official postgres image, so the project publishes its own. Swapping in a plain postgres:16 gives you a server that starts, uploads fine, and fails the moment smart search runs.

For the same reason, the database is not something you can casually move to a managed service. Keep the volume on the local SSD, and keep the pg_dump backup routine.

docker exec immich-db psql -U immich -d immich -c '\dx'
# expect vectorchord and vectors extensions in the list

Storage layout and the external library question

By default Immich copies every upload into its own library directory and organises it by user and date. That is the right default: it owns the files and the database is the source of truth.

An external library points at an existing folder on the NAS and indexes it in place. That is what people with a 300 GB existing photo folder want, and it works — but the folder must be mounted read-only or Immich will move and rename files in a structure you already had opinions about.

# external library mount, read-only on purpose
      - /mnt/nas/photos-archive:/mnt/photos-archive:ro

compose file

Drop the whole file at /srv/homelab/immich/compose.yaml. Tags are pinned, never latest: rolling back on a Pi is far more work than upgrading.

services:
  immich-server:
    image: ghcr.io/immich-app/immich-server:v1.129.0
    container_name: immich-server
    restart: unless-stopped
    ports:
      - "2283:2283/tcp"
    environment:
      TZ: Asia/Shanghai
      DB_HOSTNAME: immich-db
      DB_USERNAME: immich
      DB_PASSWORD: ${IMMICH_DB_PASSWORD}
      DB_DATABASE_NAME: immich
      REDIS_HOSTNAME: immich-redis
      IMMICH_MACHINE_LEARNING_URL: http://immich-ml:3003
    volumes:
      - /srv/homelab/immich/library:/usr/src/app/upload
      - /etc/localtime:/etc/localtime:ro
    depends_on:
      immich-db:
        condition: service_healthy
    networks: [rack]

  immich-ml:
    image: ghcr.io/immich-app/immich-machine-learning:v1.129.0
    container_name: immich-ml
    restart: unless-stopped
    volumes:
      - /srv/homelab/immich/model-cache:/cache
    networks: [rack]

  immich-redis:
    image: redis:7.4-alpine
    container_name: immich-redis
    restart: unless-stopped
    networks: [rack]

  immich-db:
    image: ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0
    container_name: immich-db
    restart: unless-stopped
    environment:
      POSTGRES_USER: immich
      POSTGRES_PASSWORD: ${IMMICH_DB_PASSWORD}
      POSTGRES_DB: immich
    volumes:
      - /srv/homelab/immich/db:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U immich"]
      interval: 10s
      timeout: 5s
      retries: 6
    networks: [rack]

networks:
  rack:
    external: true

Hardening checklist

• registration is closed after the household accounts are created, so the instance cannot be joined by anyone who finds the URL
• upload access is over the LAN or through WireGuard, never a forwarded port
• the database listens on the container network only and has no published port at all
• the machine learning container has no ports and no internet access beyond the model download at first start

Verify it went in clean

• A photo uploaded from the phone app appears in the timeline within a few seconds and has a thumbnail
• Smart search works for an obvious query like 'dog', which proves the vector extensions and the ML worker are both functioning
• The nightly pg_dump restores into a scratch database with the same asset count
• The library directory on disk contains readable year folders, so the files are usable even without the database

Hardware questions

Is a Pi 4 really enough for Immich, or is this a job for the NAS?

A Pi 4B with 8 GB handles a household library of fifty to eighty thousand photos, as long as you import in stages and keep ML concurrency at 1. The NAS with an x86 processor will do it faster and with less heat, but it also means your photo library lives on the machine that also stores your backups.

How long does the first import actually take?

Thumbnails and metadata: roughly two hundred photos per minute on a Pi 4, so 40,000 photos is about three and a half hours. With ML enabled, add about four seconds per photo across the whole library, which is where the two-day figure comes from.

Can I keep using Google Photos at the same time?

Yes, and for the first month you should. Run both, upload to Immich in parallel, and only cancel the other subscription once you have restored a photo from the Immich library and know the backup works. The migration is not reversible in the direction people assume.