Immich is a self-hosted photo and video library with a polished web interface and mobile apps that back up your camera roll automatically — much like Google Photos or iCloud Photos, but on a server you control. It includes timeline browsing, albums, sharing, maps, face recognition and smart search.

Before you start

  • Storage is the main requirement: plan for your library size plus growth (and thumbnails/transcodes add roughly 10–20%). A Storage VPS with a large disk suits this well.
  • RAM: Immich recommends at least 4 GB (6 GB+ is more comfortable), mostly for the machine-learning container.
  • CPU: imports, thumbnail generation and face detection are CPU-heavy at first; afterwards, load is light.
  • Docker and Docker Compose — see installing Docker on Ubuntu.
  • A domain or subdomain (e.g. photos.example.com) for HTTPS.

Immich is under active development and releases frequently; read the release notes before upgrading.

1. Get the official Compose files

Immich publishes a docker-compose.yml and an example .env with every release. Always use the files for the version you install:

mkdir -p ~/immich && cd ~/immich
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

2. Configure .env

UPLOAD_LOCATION=/srv/immich/library
DB_DATA_LOCATION=/srv/immich/postgres
TZ=Asia/Hong_Kong
IMMICH_VERSION=release
DB_PASSWORD=change-to-a-long-random-string
  • UPLOAD_LOCATION — where originals, thumbnails and encoded videos go. Put it on your large disk.
  • DB_DATA_LOCATION — the PostgreSQL data; should be on local SSD storage, not a network share.
  • Pin IMMICH_VERSION to a specific version (e.g. v1.x.y) if you want controlled upgrades.
sudo mkdir -p /srv/immich/library /srv/immich/postgres

3. Start it

docker compose up -d
docker compose ps

The stack includes the Immich server, the machine-learning service, Redis (or Valkey) and PostgreSQL with a vector extension.

The server listens on port 2283. Change the port mapping in docker-compose.yml to 127.0.0.1:2283:2283 so it’s only reachable through your reverse proxy.

4. HTTPS reverse proxy

Nginx server block:

server {
    listen 80;
    server_name photos.example.com;

    client_max_body_size 50000M;

    location / {
        proxy_pass http://127.0.0.1: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_redirect off;

        proxy_read_timeout 600s;
        proxy_send_timeout 600s;
    }
}

The large client_max_body_size and timeouts allow big video uploads; WebSocket headers are needed for live updates.

sudo nginx -t && sudo systemctl reload nginx
sudo certbot --nginx -d photos.example.com

5. First login and mobile backup

Open https://photos.example.com and create the admin account. Then:

  1. Install the Immich app (iOS / Android).
  2. Enter your server URL and log in.
  3. Choose albums to back up; enable background backup.

Initial uploads of a large library take time — let the phone back up on Wi-Fi and power.

6. Import an existing library

For thousands of photos from Google Takeout or a hard drive, use the Immich CLI from your computer rather than the browser:

npm install -g @immich/cli
immich login https://photos.example.com YOUR_API_KEY
immich upload --recursive /path/to/photos

Create the API key under Account Settings. Tools such as immich-go handle Google Takeout archives including their metadata files.

Or add an external library — a folder on the server that Immich indexes in place without copying.

7. Machine learning on a small server

Face recognition and smart search run in the immich-machine-learning container. On a CPU-only VPS, the first pass over a big library takes a while. In the admin settings you can reduce concurrency for jobs, choose smaller models, or disable features you don’t need to save RAM and CPU.

8. Backups — essential

A photo library is irreplaceable. Back up two things:

  • The database — Immich creates automatic database dumps in UPLOAD_LOCATION/backups (check the admin settings); or docker compose exec database pg_dumpall ….
  • The upload location — originals (library/, upload/) and profile data; thumbnails can be regenerated.

Copy them offsite with restic or Borg — see automated VPS backups — and test a restore.

9. Updating

cd ~/immich
docker compose pull
docker compose up -d
docker image prune -f

Check release notes first: some releases require changes to docker-compose.yml or .env.

Immich vs PhotoPrism vs Nextcloud Photos

Immich focuses on a phone-first backup experience similar to Google Photos. PhotoPrism is strong at organising existing archives. Nextcloud’s photo features are part of a broader file-sync suite. Compare them in Immich vs PhotoPrism.

Disk space drives everything here; a Storage VPS offers 500 GB of SSD with enough RAM to run Immich comfortably.

  • Immich
  • Self-Hosting
  • Photos