The complete guide to self-hosting Immich

Two years ago I moved my family's photos off Google Photos and onto an Immich server I run myself, and I'll say the quiet part first: it's been one of the most satisfying pieces of self-hosting I've done, and there were three separate evenings where I questioned every decision that led me there.

This guide is both of those truths, organized. What Immich is, what it takes to run well, where it bites and the order I'd do everything in if I were starting today. Where a topic deserves depth, I'll point you to the dedicated tutorial we've written for it, so think of this page as the map and the ten guides linked from it as the terrain.

What is Immich

Immich is an open-source, self-hosted photo and video platform: your own Google Photos running on hardware you control. The comparison is the project's explicit design goal rather than marketing shorthand, and it delivers on the parts people assume can't work without a trillion-dollar backend. The phone app backs up your camera roll automatically. Machine learning runs face recognition and a search that understands "kids in the pool at sunset". There are albums, shared links, a map of everywhere you've photographed and the "one year ago today" lane that makes people sentimental at breakfast.

The project's trajectory matters when you're trusting it with your photos, so the short version: after years of famously fast development, the core team shipped the stable v2.0 in October 2025 with 78,000 GitHub stars and over 1,500 contributors behind it, and the team works on it full time under FUTO's funding rather than as a side project. Since stable, versioning is semantic and compatibility is a stated promise instead of a hope. I watched the beta years up close; the difference in upgrade anxiety between then and now is night and day.

What Immich isn't: a photo editor (basic adjustments only), a Lightroom replacement or a sync-everything file platform like Nextcloud. It does photos and videos, deliberately. I consider that focus the reason it's good.

What you need to run Immich

Honest requirements, not minimums. Immich runs as four Docker containers, and the machine-learning one is why the official floor of 4 GB RAM should be treated as a real floor; give it 2 to 4 vCPU and the initial indexing of your library goes from days to hours. Then there's the question that decides everything else: where the server lives.

A home machine (old PC, NAS, mini box) costs nothing monthly and puts your photos physically in your house, at the price of managing remote access through your router and your ISP's moods. A VPS inverts the trade: static IP, real bandwidth, no port forwarding and the photos live in a datacenter you trust instead of a closet that can flood. I've run both and settled on the VPS for one unglamorous reason: my family's backups can't depend on my home internet being up. Disk is the budget line either way, because a photo library only grows, and phone cameras now produce files that make 2015 look quaint. Count your library, double it, plan for that.

If you go the server route, the full walkthrough is our Immich install guide: Docker Compose, the two official files, the .env settings with teeth (UPLOAD_LOCATION placement, the alphanumeric-only database password) and the first-run wizard. Deployment-wise we ship Immich as a 1-click template on the Immich VPS plans, which collapses that guide's first half into a checkout page; the second half, connecting phones and setting habits, no template can do for you.

Getting it online safely

An Immich server your phone can't reach from the coffee shop is a demo, so the networking layer is not optional homework. The good news is the surface is small: one port (2283) faces the world, everything else stays inside Docker, and the right production setup hides even that behind a reverse proxy speaking HTTPS on a domain. Which port does what, the firewall rules per scenario and the Caddy config I run myself are in the Immich ports guide.

Do this part before inviting anyone. Retrofitting HTTPS after the family's apps are configured means touching every phone twice, and I've done that walk of shame. Ask me how the "it's temporary" plain-HTTP setup went.

Getting the family to use it

Here's the part no other guide told me: the technical install is maybe a third of the project. The rest is adoption, and adoption is won or lost in the phone app's backup settings. Each person needs the app pointed at your server, background backup enabled and the right albums selected, five minutes per phone that you should do personally rather than describe over dinner.

After backup, the features sell themselves in a specific order. Smart search first (search "passport" in front of someone who's been scrolling for theirs, it's a party trick that converts skeptics). Then faces, named in an evening. Then partner sharing, the feature couples don't know they need until it quietly ends the "send me those pics" ritual forever. The full tour, including the sharing modes and the utilities people find months late, is the how to use Immich guide.

The maintenance reality

Immich needs two habits from its admin, and they're the two that separate a calm year from a stressful one.

First, deliberate updates. The project ships fast (a feature I'm grateful for weekly) and it labels breaking changes honestly, which only helps if you read them. My routine is monthly-ish: skim release notes, pin the exact version, pull, verify. The whole discipline, including why downgrading is off the table and the phones-before-server rule on majors, is the Immich update guide.

Second, real backups. Immich dumps its own database nightly (a genuinely great default), and that covers half of what matters; your photo files are the other half, and they need to leave the machine. The two-halves model, the rsync and restic setups and the restore drill you run exactly once are in the backup guide, and I'd rank it the most important link on this page. Photos are the one dataset with no second copy out in the world.

When something breaks

Things will occasionally break, and after two years I can report the breakage is boring and repetitive, which is the best kind. Two failure modes cover nearly everything.

Gray tiles saying "error loading image" while everything else works: that's the thumbnail pipeline or the path to it, almost never your actual photos, and the fix ladder (regenerate thumbnails, check disk, fix the proxy limits) lives in the error loading image guide. The whole page refusing to load at all: that's a five-layer walk from container health to browser cache, written up in the web UI troubleshooting guide. Between those two articles you've got maybe 95% of the tickets my household has ever filed with its sysadmin, who is me, at dinner.

The root cause behind a suspicious share of both: a full disk. Photo servers grow toward full disks by nature, so put a usage alert at 85% and half this section retires itself.

Growing into the power features

None of these belong in week one. All of them are why Immich keeps feeling better in month six.

External libraries solve the archive problem: twenty years of photos in folders you don't want reorganized. Immich indexes them read-only, in place, and they get search and faces like everything else; setup and the pitfalls are in the external libraries guide. The storage template makes Immich file uploads into human-readable, date-based folders instead of opaque IDs, a choice best made on day one and argued both ways in the storage template guide. And hardware acceleration puts a GPU behind transcoding and the ML jobs, which matters exactly twice in a server's life (the initial index of a huge library, heavy video collections) and rarely otherwise; the honest cost-benefit is in the hardware acceleration guide.

Immich or the alternatives

Fair question, quick answers.

Google Photos remains more polished and requires zero of you; the trade is compression tiers, subscription pricing that follows your library's growth and your family's memories living in an ad company's cloud.

PhotoPrism is the other serious self-hosted option, stronger for a solo photographer curating an archive, weaker at the multi-user family-backup story that is Immich's whole personality.

Ente takes the encrypted-cloud middle path, worth a look if you want privacy without hosting anything. I'll write the proper comparisons separately; the one-line version is that for "replace Google Photos for a household", Immich is the answer I give without hedging, and its been my answer for two years of putting my own family's photos on it.

The order I'd do it in

Condensing everything above into a sequence: size the server around your library and pick where it lives. Install with Docker Compose, official files only. Put the reverse proxy and HTTPS in front before anyone else touches it. Connect the phones, do each one yourself. Set up the offsite backup the same week and run the restore drill once. Decide on the storage template now, not later. Then live with it a month before touching external libraries or GPU anything, and read release notes forever. That's the whole path, and each step links to its own map above.

The payoff, since I promised the human perspective: somewhere around month three, the server stops being a project and becomes infrastructure. Photos appear because phones were near wifi. Search finds the passport.

The year-ago lane ambushes you with a kid two sizes smaller. Nobody in the house thinks about where any of it lives, except one person, occasionally, with coffee, reading release notes and feeling quietly smug about owning it all.