Host Immich on Your Own VPS

Why self-host Immich on a VPS

What self-hosting Immich brings

• Automatic backup from iOS and Android as soon as a photo is taken, like a private cloud.
• Facial recognition and semantic search run on your server, with no data sent to a third party.
• Capacity equal to your VPS disk: no imposed quota, no per-GB billing.
• Album sharing via a secure link that you control and can revoke at any time.
• Multi-user support: each member of the household or team has their own isolated library.
• EXIF metadata, maps and timelines kept locally, with no advertising exploitation.

Hardware and software requirements

Deploy Immich step by step

1. 01

   Prepare the VPS and storage

   Update the system, install Docker, then create a dedicated mount point for media, for example /mnt/photos, separate from the system disk. Enable at least 2 GB of swap for the machine learning service.

2. 02

   Retrieve the official compose file and the .env

   Download the docker-compose.yml and the example.env file from the Immich repository with wget. Rename it to .env, then set UPLOAD_LOCATION=/mnt/photos, the database password and DB_DATA_LOCATION to a persistent volume.

3. 03

   Understand the three services (v3+)

   Since version 3.0.0, the stack starts immich-server, immich-machine-learning and database (PostgreSQL with pgvector). Redis is no longer a separate service — it is embedded in the Immich server. The pgvecto.rs extension has been removed: do not use the old database image ghcr.io/immich-app/postgres, which has been replaced by the official PostgreSQL 17 image with pgvector.

4. 04

   Launch the stack and create the administrator

   Run docker compose up -d and wait for the large ML images to download. Open port 2283 internally, then create the administrator account via the web wizard before inviting other users.

5. 05

   Secure with a reverse proxy and SSL

   Place Caddy in front of the server: photos.yourcompany.com { reverse_proxy immich-server:2283 }. Increase the proxy's maximum upload size (client_max_body_size on Nginx) because videos can be large, otherwise mobile uploads fail.

6. 06

   Configure the mobile app

   Install Immich from the App Store or the Play Store, enter https://photos.yourcompany.com as the server URL, sign in, then enable automatic camera roll backup to continuously replicate your new photos.

Troubleshoot machine learning errors

Diagnose and fix the ML service

1. 07

   Check the Docker network

   Run docker network inspect immich_default and check whether both immich-server and immich-machine-learning appear in the Containers list. If one is missing, review the networks field in your docker-compose.yml: both services must reference the same network.

2. 08

   Detect a silent OOM kill

   Run dmesg | grep -i oom to see whether the kernel killed a process. Each OOM kill entry names the container and the amount of memory requested. An empty result does not rule out an OOM if the system has rebooted since the incident.

3. 09

   Inspect the ML container logs

   Run docker logs immich-machine-learning --tail 50 to review the last lines. A clean shutdown or a model-loading error will show up here more clearly than a silent kernel OOM kill.

4. 10

   Restart the ML service

   If the network is correct and RAM is sufficient, restart only this service with docker compose restart immich-machine-learning and watch whether jobs resume within the next few minutes using docker logs -f immich-machine-learning.

Migrating from v2.4.x to v3.0.0: the mandatory path

Upgrade procedure v2.4.x → v3

1. 11

   Back up the database before anything else

   Before any upgrade, export the database with docker exec -t immich_postgres pg_dumpall -c -U postgres > backup_immich_before_v3.sql. Also keep your UPLOAD_LOCATION folder. A failed HNSW migration halfway through without a backup leaves the database in an inconsistent state.

2. 12

   First upgrade to version 1.132.3

   Edit docker-compose.yml to use version v1.132.3 (exact tag) on both immich-server and immich-machine-learning. Run docker compose pull && docker compose up -d. Let the server start completely and verify that background jobs resume without errors in docker logs immich-server.

3. 13

   Switch to the official PostgreSQL image (v3 only)

   v3 uses the official PostgreSQL 17 image with pgvector, not the custom ghcr.io/immich-app/postgres image. In the docker-compose.yml provided with v3, the database service points to the official postgres:17-bookworm image with the pgvector extension. Use the official v3 compose file and do not reuse the v2 file.

4. 14

   Upgrade to v3.0.0 and wait for HNSW reindexation

   Replace the tags with v3.0.0 and pull the images: docker compose pull && docker compose up -d. The HNSW migration starts automatically on first launch. During this phase, the server remains available but smart search and facial recognition are suspended. Follow progress in docker logs -f immich-server: a Finished migration line confirms completion. On a library of 50,000 photos, expect between 10 and 30 minutes depending on the number of vCPUs allocated.

5. 15

   Verify background jobs after migration

   Open the web interface, go to Administration → Jobs and confirm that no jobs are in an error state. If any Smart Search or Face Detection tasks are stalled, restart them from the interface. The new HNSW vectors are computed once: subsequent imports are indexed normally.

Immich v2 vs v3: what changes in practice

Scroll the table