Immich replaces a cloud photo library and makes you the backup department

01A photo service with the server on your side

The immich-app/immich README describes a high-performance, self-hosted photo and video management solution. Its feature table covers mobile and web: upload and viewing, automatic and background backup from the phone, duplicate prevention, albums and shared albums, partner sharing, public sharing, RAW formats, EXIF and map views, search by metadata, objects, faces and CLIP, facial recognition and clustering, memories, tags, a folder view, OAuth sign-in and API keys. A public demo instance is linked from the README.

The README opens with a warning to always follow a 3-2-1 backup plan for photos and videos, and that warning is the right frame for the whole project. Immich gives a household the features of a cloud photo app, and the server it runs on becomes the place where years of irreplaceable files live. Everything else in this guide follows from treating that server as a storage system first and an app second.

02The requirements are real

The requirements page recommends a 64-bit Linux or Unix-like system and says non-Linux hosts tend to give a poor Docker experience and are strongly discouraged, with Docker Desktop on Windows or macOS as fallbacks. Memory should be at least 6 GB, with 8 GB recommended, and the CPU at least 2 cores, with 4 recommended; a 4 GB system can run with machine learning features disabled. Immich runs on amd64 and arm64, and since v3 the machine learning container on amd64 needs the x86-64-v2 microarchitecture level.

Storage has its own rules. The library filesystem should support Unix ownership and permissions, thumbnails and transcoded video add 10 to 20 percent on average, and the PostgreSQL data directory, typically 1 to 3 GB, should sit on local SSD storage and never on a network share. Docker inside LXC containers is not recommended. Plan disks for the size of the library in five years rather than today, and give the database the fastest local disk available.

03Installing with Docker Compose

The supported route downloads docker-compose.yml and example.env from the latest release into a directory of your choice, renames the env file to .env and edits it. UPLOAD_LOCATION sets where uploaded files go, DB_DATA_LOCATION where the database lives, IMMICH_VERSION which release to run (v3 in the example, or a pinned version) and DB_PASSWORD the database password, which the docs suggest limiting to letters and digits. docker compose up -d starts the stack, and the requirements page notes that the older docker-compose command is deprecated and no longer supported.

Keep the .env and compose files in the backup set, since they record where data lives and which version runs. The docs explain that Postgres is not exposed publicly in the default setup, so its password is only used for local authentication, but replacing the default value is still sensible. If the service will be reached from outside the home network, put it behind a reverse proxy with TLS and decide whether it should be public at all or only reachable over a VPN.

04Machine learning runs on your hardware

Smart search by objects and CLIP, face detection and face clustering run in a separate machine learning container on the same host. That keeps the photos on the server instead of sending them to an outside service, and it is also why the requirements ask for more memory and, on amd64, a newer CPU instruction level since v3. On low-memory systems the machine learning features can be turned off, at the cost of smart search and face grouping.

Processing a large existing library keeps the CPU busy for a while, so import in stages and watch the job queues in the administration pages. Face recognition groups people automatically, which is convenient and also sensitive. Decide who in the household can see the people view, and remember that shared albums and partner sharing extend what other accounts can see.

05Two things to back up, every time

The backup page explains that Immich stores file paths and user metadata in the database and does not scan the library folder, so database backups are essential. It creates automatic database dumps in UPLOAD_LOCATION/backups, by default keeping the last 14 and creating one daily at 2:00 AM, adjustable in the administration settings. Those dumps contain only metadata, not photos or videos, and must be paired with a copy of the files in UPLOAD_LOCATION.

The docs also warn that they only describe what to back up; a real backup tool still has to copy it somewhere. A workable plan is a nightly job that copies the dump folder and the upload folders to a second disk and to an off-site location, plus a restore test on a separate machine a few times a year. Restoring through the web interface wipes the current database and replaces it, with a restore point created automatically first, so rehearse it before it is needed.

• Back up the database dumps and the original upload folders together, on the same schedule.
• Keep at least one copy off site and one copy that the Immich host cannot delete.
• Restore to a test instance on a schedule and open a few albums to prove the backup works.

06Upgrades follow the major version

Immich follows semantic versioning and limits breaking changes, including API and deployment changes, to major releases. The image can track a major version through a tag such as :v3. Upgrading means reading the release notes, updating IMMICH_VERSION if it is pinned, then running docker compose pull and docker compose up -d. Patches are not backported to earlier versions, and downgrading, even within the same minor version, is not supported.

The server only works with mobile apps from its own major version, while apps usually support the current and the previous major, so the docs recommend upgrading mobile clients before the server. Take a database dump just before upgrading and keep it with a copy of the compose file. The GitHub releases API listed v3.3.5, published October 21, 2026, as the latest release when this guide was checked; its notes recommend updating promptly because of security patches in its dependencies.

07External libraries and where metadata lives

Existing folders can be added as external libraries, which Immich scans and shows in the timeline like uploaded assets. The documentation lists the caveats. An external library belongs to one user, chosen when it is created. If a file is deleted from disk, Immich moves the asset to trash on the next rescan, and after 30 days it is removed along with any metadata added in Immich. Albums, descriptions and other metadata added in Immich are not written back to the files.

That last point matters to anyone who expects the folder to stay the source of truth. Moving a file within the library makes Immich treat it as a new asset, and metadata attached to the old one is lost on rescan. If the existing folder structure is what matters, treat it as read-only from Immich's side and accept that albums live in the database. If Immich is meant to become the primary library, upload into it and back up its storage instead.

08License and fit

Immich is licensed under the AGPL-3.0. The license's source-sharing conditions are written around offering modified versions to other users over a network, so they matter most to a business that changes Immich and hosts it for others. The project ships Android and iOS apps alongside the server, and its documentation for installation, administration and development lives at docs.immich.app.

Immich fits people who want a cloud-style photo experience without a cloud provider and who will treat the server as important storage. It is a poor fit for anyone who wants to install it and forget it. Start with one user and one phone, prove a full backup and restore, then add family members. The order matters: once others depend on it, losing the database means rebuilding albums, faces and sharing for everyone.