Immich

Immich is an open-source app for backing up and browsing your photos and videos, and it runs on a server you own rather than someone else's cloud. You get the phone backup, timeline and smart search of a hosted service, while the files and the data about them stay on your own hardware.

What 'self-hosted' means here

A hosted photo service keeps your pictures on the provider's servers. You pay with a subscription, with storage limits, or by trusting the company with everything in your camera roll, including where you were and who you were with.

A self-hosted app flips that around. You install the software on a machine you control, such as a home server, a NAS (a network storage box), an old laptop or a rented virtual server, and your devices talk to that instead. Immich is that kind of app for photos and videos. The code is open source under the GNU AGPL v3 licence, so anyone can read it, run it and change it.

In return for control over storage and privacy, you take on the jobs a provider normally does for you: keeping the server running, updating it and backing it up. The Cloud vs. on-prem video covers the same trade-off for whole companies.

What Immich is made of

Immich runs as a small set of services side by side, usually as Docker containers:

• The server handles the API that the apps call and runs background jobs such as making thumbnails, reading metadata and converting videos.
• The machine learning service is a separate Python service that runs the models behind smart search and face recognition. Because it is its own container, it can run on a different, more powerful machine, or be switched off.
• Postgres stores everything about your library except the files themselves: users, albums, sharing settings, metadata and the search data.
• Redis holds the queue of background jobs waiting to run.
• The clients are a mobile app, a web app and a command-line tool for bulk uploads.

The photos and videos themselves live as ordinary files in a folder you choose, called the upload location. The database only describes them.

What happens when a photo is backed up

An upload sets off a chain of background jobs. One job finishing triggers the next, and the machine learning work only starts once there is a thumbnail to work on. Here is the path a single photo takes:

This is why a big first import takes a while. Every photo queues several jobs, and you can watch them work through in the admin page's job queues.

Automatic backup from your phone

The mobile app is how most people use Immich day to day. You sign in with your server's address, choose which albums on the phone to back up, and turn backup on. From then on, new photos in those albums upload on their own, the way they would to a hosted service.

Uploads run one way, from the phone to the server. The app uploads new photos when you open it and from time to time in the background. On Android you can limit background uploads to when the phone is charging. On iOS the system decides when background work runs, so opening the app now and then keeps backups moving.

Finding photos again

Backing up thousands of photos is only half the problem. The other half is finding the one you want. Immich gives you three ways in.

By date and place

Every photo shows up in a timeline, newest first, built from the date the camera wrote into the file. Most phones also record a GPS position. Immich turns that position into a city, state and country (reverse geocoding), so you can search for a place by name or browse your photos on a map. Camera model, lens, file name and folder are searchable too.

By what is in the picture

Smart search lets you type 'cat on a couch' and get photos of exactly that, even though nobody tagged them. It uses a CLIP model, which is trained on images paired with text descriptions. CLIP turns an image into a list of numbers, a vector, and it turns a piece of text into a vector in the same space. A photo and a phrase that describe the same thing end up with vectors close together.

So when you search, Immich turns your words into a vector and asks Postgres for the photos whose vectors are nearest to it. Postgres can do that quickly thanks to a vector extension, VectorChord. The Vector Database video explains this kind of nearest-match search in more depth.

Two things follow from this design. Search works on meaning, not keywords, so 'fish dinner' can find a plate of tuna with no caption at all. And the matching happens on your own machine: the model runs in your machine learning container, so your photos aren't sent to an outside AI service to be understood.

By who is in it

Face recognition works in two stages. First a detection model finds each face in a photo and draws a box around it. Then a recognition model turns each face into a vector, so that two photos of the same person produce vectors close together.

Immich then groups those face vectors into clusters, using an algorithm based on DBSCAN, which builds groups from points that sit densely together. Each cluster becomes a person. You give the person a name once, say 'Grandma', and every photo of her becomes searchable by that name, including ones uploaded later. When the grouping gets it wrong, you can merge two people or move a face to the right one.

A worked example: a home server in four steps

Say you have a small home server with Docker installed and a large disk mounted at /srv/immich. Immich's documentation asks for at least 6 GB of RAM and 2 CPU cores.

First, make a folder and download the official Compose file and example settings:

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

Next, edit .env to say where your files and database live, and set a real database password:

UPLOAD_LOCATION=/srv/immich/library
DB_DATA_LOCATION=/srv/immich/postgres
DB_PASSWORD=LongRandomLettersAnd123
TZ=Europe/London

Then start everything:

docker compose up -d

Finally, open http://<server-ip>:2283 in a browser. The first account you register becomes the admin. Install the mobile app, enter the same address, pick your albums and turn on backup. If Compose is new to you, the Docker Compose video explains how one file starts several containers together.

The trade-offs

Self-hosting moves work onto you. Before you move a whole camera roll, know what that work is.

• You run the operations. Updates, disk space, power cuts and a failed drive are now your problems. Immich moves quickly, so read the release notes before updating.
• Reaching it from outside your home takes care. Your phone can back up over home Wi-Fi with no extra set-up. To back up from anywhere, you need a VPN or a reverse proxy with HTTPS, and putting a server on the open internet carelessly is a security risk.
• Machine learning needs hardware. Smart search and face recognition are the heaviest jobs. A low-power box will get through a large library, just slowly.

One server is not a backup

If your only copy of your photos is the Immich server, a single dead disk loses everything. Immich's own docs recommend a 3-2-1 strategy: three copies of your data, on two different kinds of storage, with one copy off-site.

Two things need backing up. Immich dumps its database automatically, daily at 2:00 by default, keeping the last 14, into a backups folder inside the upload location. The originals live in the library, upload and profile folders there. Copy those off the machine regularly, to a second disk and to somewhere outside your home. Thumbnails and converted videos can be rebuilt, so they matter less.

Common mistakes

• Treating Immich as the backup: once you clear photos off your phone to free space, the server may hold the only copy, so back it up too.
• Putting the database on a network share: the settings file says network shares aren't supported for the database folder. Keep it on a local disk, even if the photo library lives on a NAS.
• Leaving the default database password: change it before the first start, using only letters and numbers.
• Expecting instant search after a big import: every photo has to go through thumbnails, metadata and machine learning first, so give the job queue time.
• Exposing port 2283 straight to the internet: use a VPN or a properly configured reverse proxy instead.

Key takeaways

• Immich is an open-source, self-hosted app for backing up and browsing photos and videos.
• It runs as a few services: a server, a machine learning service, Postgres and Redis, usually with Docker Compose.
• Smart search compares CLIP vectors of your words and your photos, and face recognition clusters face vectors into people, all on your own hardware.
• You control storage and privacy, and in return you run updates, security and backups yourself.
• A self-hosted server is not a backup on its own: follow 3-2-1 for the originals and the database.