Immich: self-hosted photo and video management for people leaving Google Photos

What problem Immich solves, and who ends up running it

The problem is ownership. Cloud photo services give you a searchable library, automatic phone backup, and shared albums, but the library lives on someone else's hardware under someone else's terms. Immich reproduces that shape of product on a server you control. The README describes it as a "High performance self-hosted photo and video management solution", and the feature table backs the claim with the things people actually use: upload and view photos and videos, auto backup when the mobile app is opened, duplicate prevention, albums and shared albums, EXIF and map metadata, search by metadata, objects, faces and CLIP, facial recognition and clustering, Memories, partner sharing, and a global map.

The audience is narrower than the feature list suggests. You need a host that stays powered on, a place to put the media, and enough patience to run containers. The repository ships a deployment directory and a docker directory, plus an install.sh at the top level, which tells you the maintainers expect installation to be a server-side operation rather than an app store download. If you want a photo app and not a small piece of infrastructure, this is the wrong shape of project.

How the pieces fit: server, web, mobile, machine-learning

The repository layout is the architecture. Top-level directories include server, web, mobile, machine-learning, packages, open-api, deployment, docker, e2e, i18n and docs. That is a monorepo with a clear split: the server holds the library and the API, web is the browser client, mobile is the phone client, and machine-learning is a separate service rather than a library compiled into the server.

That last split matters. Search by objects and faces, and CLIP-based search, are the features most likely to need real CPU or a GPU, and isolating them in their own directory means they can be scaled or restarted independently of the API. The open-api directory indicates the HTTP surface is generated from a specification rather than hand-written per client, which is why the web and mobile apps can expose the same features. The packages directory holds shared code across those clients.

The root package.json is small: it is a private workspace named immich-monorepo at version 3.2.0, using [email protected] with an engines constraint of pnpm >=10.0.0, and its only scripts are format and format:fix, both scoped to the i18n directory. That is a deliberate signal. The root manifest is not the build entry point for the server or the apps; it is workspace plumbing and translation formatting. If you are trying to build Immich from source, the root package.json will not tell you how.

Installing Immich with Docker and doing a first upload

The README does not inline install steps. It points at the documentation site, listing Installation at docs.immich.app/install/requirements and noting that "You can find the main documentation, including installation guides, at https://immich.app/". There is also an install.sh in the repository root, and the release notes list v3.1.0, v3.0.3 and the v3.2.0-rc.1 pre-release. Treat the documentation site as the source of truth for the current compose file, because the environment variables and image tags change between releases and this article cannot verify them for your version.

The shape of a Docker deployment is what the deployment and docker directories exist to support. A compose file declares the services, and the server needs a database and a media location. The exact keys are version-specific, so read the compose file that ships with the release you are installing rather than copying a snippet from a blog post:

mkdir -p ./immich-app && cd ./immich-app
# fetch the compose file and .env for your release from the documentation site
# then start the stack
docker compose up -d

Once the stack is up, the web client is the first thing to open in a browser, because the feature table marks administrative functions (user management) as web-only and mobile as No. Create your account there, then install the mobile app and point it at your server using the Server Endpoint URL field. The demo at demo.immich.app uses exactly that field, with the credentials [email protected] and demo, which is a useful way to see the app's flow before you commit hardware.

For a first real upload, install the mobile app and let it run its backup. The feature table describes auto backup as happening "when the app is opened", with background backup listed as a separate mobile feature. Selective album backup is mobile-only. On the web side, uploads and downloads work, but auto backup is marked N/A, so the phone is the intended ingestion path.

Where Immich will disappoint you

The README opens with a warning, not a feature: "Always follow 3-2-1 backup plan for your precious photos and videos!" That is not boilerplate. A self-hosted library concentrates your media in one place that you also administer, which means a bad disk, a bad upgrade, or a bad deletion is your problem. The project does not document rollback in the README, so the recovery story for a failed upgrade is something you should confirm in the documentation before you upgrade rather than after.

Remote access is the second friction point. The feature table lists offline support as Yes for mobile and No for web, which is a real constraint if you expect the browser client to work on a flaky connection. Exposing the server to the internet is a decision the README does not make for you; the documentation is where you would look for the supported approach, and the search questions around remote access and Tailscale suggest this is where new users get stuck.

The third limitation is scope. Administrative functions are web-only. Tags are web-only. 360 degree image display is web-only. If your mental model is "the phone app does everything", the feature table will correct it. And if you are running this on a NAS or a low-power box, the machine-learning service is the part to watch, because facial recognition, object search and CLIP search all depend on it and the repository keeps it as a separate workload for that reason.

Immich versus PhotoPrism: different defaults, different work

PhotoPrism is the comparison people reach for, and the difference is in what each project treats as the center of gravity. PhotoPrism is built around browsing and organizing an existing library, with its own indexing and classification pipeline. Immich is built around the phone as the source of truth: auto backup when the app opens, selective album backup, background backup, duplicate prevention, LivePhoto and MotionPhoto backup and playback. The feature table reads like a list of mobile backup behaviours with a web client attached, not the other way around.

That distinction decides the choice. If your photos already sit on a disk and you want a better way to browse them, the backup-oriented design of Immich is not the part you need. If your photos are on a phone and you want them off the cloud, Immich's mobile backup path is the feature you are actually buying, and the web client is where you administer it. Multi-user support and partner sharing exist in both directions of that comparison, but the ingestion model is where they diverge.

Licence, upgrades and what maintenance costs you

Immich is licensed AGPL-3.0, and the LICENSE file sits at the repository root. The practical implication for most self-hosters is that running it on your own server for your own library is the ordinary case. The AGPL matters more if you modify Immich and offer it to others over a network, because that triggers source-availability obligations. This is a description of the licence, not legal advice; read the licence text and talk to a lawyer if you plan to build a service on top of it.

Upgrade cost is the real recurring expense. The project ships release candidates, and v3.2.0-rc.1 is one, so you have to decide whether your library tracks stable releases or pre-releases. The repository carries a renovate.json, which means dependency updates are automated on the maintainer side and will arrive in your image tags without you doing anything. The last push to the repository was on 2026-08-28, and the most recent stable release listed is v3.1.0 from 2026-07-29. That cadence is fast enough that pinning a version and reading release notes before upgrading is cheaper than upgrading on every tag.

Editorial conclusion

Adopt Immich if you have a machine that stays on, you are comfortable running Docker containers, and you want mobile backup plus web browsing against storage you control. Do not adopt it if you want a managed service, if nobody will own backups, or if you expect the mobile app to cover administration, since the feature table marks administrative functions as web-only. Before you migrate anything, verify three things: that your host meets the requirements listed at docs.immich.app/install/requirements, that your backup routine actually restores, and that the server endpoint URL your phone will use is reachable from outside your home network if you need remote access. The README's own warning is the right place to start, not a footnote.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes