Hobbyist's Hideaway LogoHobbyist's Hideaway
HomeLab
•14 min read

Immich Docker Compose Setup Guide (2026): Self-Host Google Photos

Share
Immich Docker Compose Setup Guide (2026): Self-Host Google Photos
On this page(12 sections)

Immich is the closest thing to Google Photos you can run at home: automatic phone backup, face recognition, a map, "on this day" memories and a search box that understands "dog on the beach". The right way to install it is with the official docker-compose.yml and .env from the Immich GitHub release, and it runs happily on a cheap Intel N100 mini PC. This guide covers the full setup, plus the parts most tutorials skip: hardware acceleration, external libraries, remote access, real backups and safe updates.

What Is Immich (and Is It Free?)

Photo memories flowing into a small home server on a shelf
Immich keeps your photo library on hardware you own instead of in someone else's cloud.

Immich is an open-source, self-hosted photo and video platform. You run the server, your phone uploads to it, and you browse everything in a fast web app or the mobile apps. The project went "stable" with v2.0 in late 2025 and is now on the v3 release line.

What you get out of the box:

  • Automatic backup from iOS and Android, in the background.
  • Face recognition, with people you can name and merge.
  • Smart search using a CLIP model, so "red car in the snow" finds photos with no tags at all.
  • Map, timeline and memories, just like Google Photos.
  • Albums, shared links and partner sharing (your partner's photos appear in your timeline).
  • Multiple users, each with their own library and storage quota.
  • Live/motion photos, RAW files and video, with transcoding for smooth playback.
  • Duplicate detection to clean up years of double uploads.

Is Immich free? Yes. It's licensed under AGPL-3.0, and every feature is available to everyone. There's an optional one-time "supporter" purchase to fund development, but it doesn't unlock anything. Your only real cost is the hardware and the disks.

Hardware: What You Need

Immich is heavier than most homelab apps because of its machine learning (ML) container and Postgres database. Here are the official numbers:

ResourceMinimumRecommendedNotes
RAM6 GB8 GBWith 4 GB you can run it with ML disabled
CPU2 cores4 coresamd64 or arm64
Database diskLocal SSDLocal SSDPostgres is typically 1–3 GB; never on a network share
Photo storageYour library size+ 10–20%Thumbnails and transcoded video add overhead
OS64-bit LinuxDebian / UbuntuDocker with the Compose plugin

One v3 detail: on amd64, the ML container now requires a CPU with the x86-64-v2 instruction level. Anything from the last decade qualifies, including every N100, N150 and N305 chip.

Will Immich run on an N100?

Yes, and it's one of the best value Immich boxes you can buy. A 16 GB N100 mini PC has plenty of RAM, idles at a few watts, and its Intel iGPU gives you:

  • Quick Sync for hardware video transcoding (fast, low-power playback of phone videos).
  • OpenVINO support for running the ML models on the iGPU instead of the CPU.

The one slow part is the first import. Face detection and smart search indexing on tens of thousands of photos can take many hours on a low-power CPU. It's a one-time job, and new photos are processed as they arrive.

Shopping for hardware? See our N100 vs N150 vs N305 mini PC guide and the low-power N100 homelab overview.

Where to run it

  • Proxmox: a Debian VM, or a Docker-enabled LXC, keeping the database on local SSD storage. Our Proxmox on N100 setup guide covers creating both.
  • TrueNAS SCALE: Immich is in the apps catalog. It's convenient, but you give up some control over the compose file. See our TrueNAS SCALE guide.
  • Any Linux box with Docker: the path this guide follows. New to Docker? Start with self-hosting with Docker.

Immich Docker Compose Install (the Official Way)

The most common Immich mistake is copying a hand-written compose file from an old blog post or forum thread. Immich's stack (server, ML, Valkey/Redis and a Postgres image with vector search extensions) changes between releases, and the official files are kept in sync with each version. Always start from the files attached to the latest GitHub release.

Step 1: Download the compose file and .env

mkdir ./immich-app
cd ./immich-app

wget -O docker-compose.yml https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml
wget -O .env https://github.com/immich-app/immich/releases/latest/download/example.env

Step 2: Edit the .env file

Open .env and change these values:

# Where your photos and videos are stored (lots of space needed)
UPLOAD_LOCATION=/mnt/photos/immich

# Postgres data: keep this on a LOCAL SSD, never NFS/SMB
DB_DATA_LOCATION=./postgres

# Uncomment and set your timezone
TZ=Asia/Kathmandu

# Major version metatag (or pin an exact release, e.g. v3.x.y)
IMMICH_VERSION=v3

# Change this! Letters and numbers only
DB_PASSWORD=ReplaceWithALongRandomString

DB_USERNAME=postgres
DB_DATABASE_NAME=immich

Generate a password with pwgen 32 1 or openssl rand -hex 24. Stick to A–Z, a–z and 0–9, as the docs recommend.

Step 3: Start Immich

docker compose up -d
docker compose ps

Use docker compose (the plugin), not the old docker-compose binary, which Immich no longer supports. If you get an "unknown shorthand flag" error, you're on an outdated Docker package: install Docker Engine from Docker's official repository.

The Immich default port is 2283. Open http://SERVER-IP:2283, create the first account (it becomes the admin), and you're in. Older guides mention port 3001, which was the container's internal port in early versions. Ignore them.

Turn On Hardware Acceleration (Quick Sync and OpenVINO)

Both features use small helper files that live next to your compose file. Download them from the same release:

wget -O hwaccel.transcoding.yml https://github.com/immich-app/immich/releases/latest/download/hwaccel.transcoding.yml
wget -O hwaccel.ml.yml https://github.com/immich-app/immich/releases/latest/download/hwaccel.ml.yml

Hardware transcoding with Quick Sync

In docker-compose.yml, find the commented extends block under immich-server, uncomment it and set the service to quicksync:

  immich-server:
    # ...existing lines...
    extends:
      file: hwaccel.transcoding.yml
      service: quicksync

In the web UI, go to Administration → Settings → Video Transcoding Settings → Hardware Acceleration and pick Quick Sync.

Machine learning on the Intel iGPU

Under immich-machine-learning, append -openvino to the image tag and uncomment its extends block:

  immich-machine-learning:
    image: ghcr.io/immich-app/immich-machine-learning:${IMMICH_VERSION}-openvino
    extends:
      file: hwaccel.ml.yml
      service: openvino

Run docker compose up -d again, and if ML jobs fail, go back to the CPU image. Another trick: in Administration → Settings → Machine Learning, you can point Immich at an ML container on a more powerful PC, so your gaming rig does the heavy initial indexing while the N100 runs everything else.

Proxmox LXC users: pass the iGPU into the container first (/dev/dri/renderD128, via Resources → Add → Device Passthrough on recent Proxmox versions), or neither feature will see the GPU.

Back Up Your Phone with the Immich Mobile App

Smartphone showing a photo grid with photos streaming to a home server
The Immich app uploads new photos from your phone to your server in the background.
  1. Install Immich from the App Store, Google Play or F-Droid.
  2. Enter your server URL (http://SERVER-IP:2283 at home, or your remote URL; see below) and log in.
  3. Tap the cloud icon, choose which albums to back up (for example, Camera but not WhatsApp), and enable background backup.
  4. Turn on Wi-Fi only and only while charging for the first big upload.

A few tips:

  • Keep Google Photos or iCloud running in parallel for a few weeks until you trust your setup and backups.
  • iOS background uploads are less reliable than Android's. Open the app now and then to let it catch up.
  • Migrating from Google Photos? Export with Google Takeout and import with the community tool immich-go, which reads Takeout's JSON metadata so dates and albums survive.

Add Existing Photos with External Libraries

Already have 20 years of photos in folders on a NAS? Don't upload them again. External libraries let Immich index folders in place, without moving or changing your files.

Mount the folder into the server container read-only in docker-compose.yml:

  immich-server:
    volumes:
      # keep the existing lines from the official file, then add:
      - /mnt/nas/photos:/mnt/media/photos:ro

Then:

  1. docker compose up -d
  2. Go to Administration → External Libraries → Create library and choose the owner.
  3. Add the import path /mnt/media/photos (the path inside the container) and click Scan.

The folder can live on an NFS or SMB share mounted on the host. That's fine for photos; only the database has to stay on local storage. Immich won't write to a read-only mount, so your originals stay untouched.

Remote Access: Tailscale, Reverse Proxy or Tunnel

You want backups to work when you're away from home, but don't port-forward 2283 to the internet. Pick one of these instead:

MethodEffortBest forWatch out for
Tailscale / WireGuardLowJust you and familyEvery phone needs the VPN app running
Reverse proxy + domainMediumSharing links with friendsKeep Immich updated; use strong passwords
Cloudflare TunnelLowNo open portsThe free plan limits upload size (100 MB per request), so large videos can fail

For most households, a VPN is the safest choice. We compare the options in Tailscale vs WireGuard for your homelab.

If you go the reverse proxy route, Immich needs three things: large uploads, WebSockets and long timeouts. An Nginx example:

server {
    server_name photos.example.com;

    client_max_body_size 50000M;

    location / {
        proxy_pass http://192.168.1.50:2283;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        proxy_read_timeout 600s;
        proxy_send_timeout 600s;
    }
}

Prefer Traefik? The same rules apply: see our Traefik reverse proxy guide. Once it's working, set the External domain under Administration → Settings → Server so shared links use your public URL.

Immich Backup: Protect Your Photos with 3-2-1

Immich is not a backup. It's the one place your photos live, which means a dead SSD, a bad update or an accidental delete can take everything. Follow the 3-2-1 rule: 3 copies, on 2 different types of storage, 1 off-site.

What to back up

Immich needs two things to restore: the database and the files.

Path inside UPLOAD_LOCATIONWhat it isBack up?
library/, upload/, profile/Your original photos, videos and avatarsYes, always
backups/Immich's automatic database dumpsYes
thumbs/, encoded-video/Generated thumbnails and transcodesOptional (can be regenerated)

Database dumps

Immich already dumps its database every night at 2:00 AM and keeps the last 14 dumps in UPLOAD_LOCATION/backups. Change the schedule in Administration → Settings → Database Dump Settings. You can also make a manual dump before risky changes:

docker exec -t immich_postgres pg_dump --clean --if-exists \
  --dbname=immich --username=postgres \
  | gzip > "/mnt/backup/immich-db-$(date +%F).sql.gz"

Never back up the raw postgres folder while the database is running: you'll get a corrupt copy. Use the dumps.

A simple 3-2-1 plan

  • Copy 1: the live Immich library on your server.
  • Copy 2: a nightly versioned backup to a NAS or USB disk using restic, Borg, Proxmox Backup Server or ZFS snapshots. Versioned matters: a plain mirror happily copies deletions and ransomware too.
  • Copy 3: off-site, such as an encrypted restic repo on Backblaze B2 or a Raspberry Pi at a relative's house.

Back up the database dumps before the files. If the two drift slightly, you end up with a few extra files, rather than database entries pointing at photos that don't exist. To restore, the web UI now offers Administration → Maintenance → Restore database backup, and the docs cover full command-line restores. Test a restore once, on a spare VM, before you need it.

How to Update Immich Safely

Immich moves fast, and updates occasionally include breaking changes. A safe routine:

  1. Read the release notes on GitHub for every version you're skipping. Breaking changes are labelled clearly.
  2. Update the mobile apps first. The server only talks to apps on the same major version, and the apps usually support the previous one too.
  3. Snapshot or back up (a Proxmox snapshot of the VM/LXC takes seconds).
  4. If you pinned an exact version, change IMMICH_VERSION in .env. With the v3 metatag you get every v3 release automatically.
  5. Pull and restart:
cd ./immich-app
docker compose pull && docker compose up -d
docker image prune

Downgrading is not supported, not even to an earlier patch release, because database migrations only run forward. If an update goes wrong, restore your snapshot or backup. Major version jumps (v2 → v3) are when you should re-download the release's docker-compose.yml and compare it to yours. Avoid auto-updaters like Watchtower for Immich.

Immich vs PhotoPrism vs Synology Photos vs Nextcloud Memories

ImmichPhotoPrismSynology PhotosNextcloud Memories
CostFree (AGPL), optional supporter keyFree Community Edition, paid tiersFree, but needs a Synology NASFree Nextcloud app
Runs onAny Docker hostAny Docker hostSynology DSM onlyA Nextcloud server
Official phone backup appYes, iOS and AndroidNo (web app; upload via third-party apps)YesVia the Nextcloud app's auto-upload
Face recognitionYesYesYesYes, with the Recognize app
Natural-language searchYes (CLIP)Label-basedBasicBasic
Existing foldersExternal libraries (read-only)Excellent, indexes in placeYesYes, indexes Nextcloud files
Multi-userYes, plus partner sharingLimited in the free editionYes (DSM users)Yes (Nextcloud users)
Feels likeGoogle PhotosA photo archive / catalogueGoogle Photos, liteA gallery inside a cloud drive

Immich vs PhotoPrism

This is the most common comparison. PhotoPrism is excellent if you already curate photos in a folder structure and mainly want to browse, search and tag them. It's mature and light on change. Immich is the better replacement for Google Photos: its phone app, background backup, sharing and timeline are far ahead. If your family will use it from their phones, pick Immich.

Immich vs Synology Photos

If you own a Synology NAS, Synology Photos is zero-effort and stable. Immich wins on smart search, development pace and hardware freedom, and many Synology owners simply run Immich in Container Manager.

Immich vs Nextcloud

Nextcloud Memories makes sense if you already run Nextcloud and want photos in the same place. As a dedicated photo app, Immich is faster and simpler to maintain.

FAQ

Is Immich free to use?

Yes. Immich is open-source (AGPL-3.0), with no paywalled features, user limits or storage limits. The optional supporter purchase is a donation with a badge, nothing more.

What is the Immich default port?

2283. Browse to http://SERVER-IP:2283 and use the same address in the mobile app on your home network. You can change the left-hand side of the ports mapping in docker-compose.yml if 2283 is taken.

Can I run Immich on a Raspberry Pi?

Yes, on a Raspberry Pi 5 with 8 GB of RAM and an SSD (arm64 is supported). Expect slow ML indexing and no hardware transcoding worth using. An N100 mini PC is a much better experience for similar money.

Can I run Immich in a Proxmox LXC?

Yes. Run Docker inside a Debian LXC (nesting enabled) or a small VM, keep DB_DATA_LOCATION on local SSD storage, and pass through /dev/dri if you want Quick Sync or OpenVINO. A VM is the more isolated option; an LXC uses less RAM.

Do I need machine learning enabled?

No. Without it you lose face recognition, smart search and duplicate detection, but backup, timeline, albums and the map all work. Disabling ML is the way to run Immich on a 4 GB machine.

Conclusion

Immich turns a low-power mini PC into a private Google Photos replacement your whole family can use. Install it from the official release compose file and .env, keep the database on a local SSD, turn on Quick Sync and OpenVINO if you have an Intel iGPU, and reach it remotely through a VPN or a properly configured reverse proxy. Then do the boring part: set up a 3-2-1 backup and read the release notes before every update.

Next up for your homelab: go paperless with our Paperless-ngx on Proxmox guide, or polish your media server with the best Jellyfin plugins and themes.

Share this article
Share

Never Miss a Project

Join our community of makers. Get the latest guides on Homelab, Electronics, and Coding delivered to your inbox.