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?)

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:
| Resource | Minimum | Recommended | Notes |
|---|---|---|---|
| RAM | 6 GB | 8 GB | With 4 GB you can run it with ML disabled |
| CPU | 2 cores | 4 cores | amd64 or arm64 |
| Database disk | Local SSD | Local SSD | Postgres is typically 1–3 GB; never on a network share |
| Photo storage | Your library size | + 10–20% | Thumbnails and transcoded video add overhead |
| OS | 64-bit Linux | Debian / Ubuntu | Docker 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

- Install Immich from the App Store, Google Play or F-Droid.
- Enter your server URL (
http://SERVER-IP:2283at home, or your remote URL; see below) and log in. - Tap the cloud icon, choose which albums to back up (for example, Camera but not WhatsApp), and enable background backup.
- 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:
docker compose up -d- Go to Administration → External Libraries → Create library and choose the owner.
- 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:
| Method | Effort | Best for | Watch out for |
|---|---|---|---|
| Tailscale / WireGuard | Low | Just you and family | Every phone needs the VPN app running |
| Reverse proxy + domain | Medium | Sharing links with friends | Keep Immich updated; use strong passwords |
| Cloudflare Tunnel | Low | No open ports | The 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_LOCATION | What it is | Back up? |
|---|---|---|
library/, upload/, profile/ | Your original photos, videos and avatars | Yes, always |
backups/ | Immich's automatic database dumps | Yes |
thumbs/, encoded-video/ | Generated thumbnails and transcodes | Optional (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:
- Read the release notes on GitHub for every version you're skipping. Breaking changes are labelled clearly.
- 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.
- Snapshot or back up (a Proxmox snapshot of the VM/LXC takes seconds).
- If you pinned an exact version, change
IMMICH_VERSIONin.env. With thev3metatag you get every v3 release automatically. - 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
| Immich | PhotoPrism | Synology Photos | Nextcloud Memories | |
|---|---|---|---|---|
| Cost | Free (AGPL), optional supporter key | Free Community Edition, paid tiers | Free, but needs a Synology NAS | Free Nextcloud app |
| Runs on | Any Docker host | Any Docker host | Synology DSM only | A Nextcloud server |
| Official phone backup app | Yes, iOS and Android | No (web app; upload via third-party apps) | Yes | Via the Nextcloud app's auto-upload |
| Face recognition | Yes | Yes | Yes | Yes, with the Recognize app |
| Natural-language search | Yes (CLIP) | Label-based | Basic | Basic |
| Existing folders | External libraries (read-only) | Excellent, indexes in place | Yes | Yes, indexes Nextcloud files |
| Multi-user | Yes, plus partner sharing | Limited in the free edition | Yes (DSM users) | Yes (Nextcloud users) |
| Feels like | Google Photos | A photo archive / catalogue | Google Photos, lite | A 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.



