.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
Immich is the self-hosted answer to Google Photos that finally feels like one: mobile auto-backup, face recognition, search that understands "beach sunset" and a development pace that shipped it from beta to stable to a v3 major in about a year. That pace is also the thing to respect when you install it.
This guide sets up Immich with Docker Compose on a VPS the official way, with the decisions that save you pain at upgrade time made correctly on day one.
Sizing the server for a photo library
Immich runs four containers (server, machine learning, Postgres, a Redis-compatible cache) and the machine-learning part is the hungry one, doing face detection and smart search indexing. Practical floor for a comfortable experience: 4 GB of RAM and 2 vCPU, with 4 vCPU making the initial library indexing dramatically less tedious. The official requirements say as much, and I'd treat anything below that as a demo, not a home for your photos.
Storage is the real planning question. Photos accumulate in one direction only, and phone cameras now produce 5 MB HEICs and 100 MB videos without asking. Count your current library, double it and pick the plan from there; when the math points past what NVMe plans offer per dollar, a storage VPS is built for exactly this shape of problem. Postgres, on the other hand, wants fast disk, so on split setups keep the database on NVMe and point only the media at bulk storage.
Step 1: Get Docker and the official files
You need Docker Engine v25 or newer with the compose plugin (docker compose version to check; note the space, the old hyphenated docker-compose binary is deprecated). On a fresh Ubuntu VPS, Docker's official convenience script or the Docker VPS template both get you there in a minute.
Make a home for Immich and pull the two release files:
mkdir -p /opt/immich && cd /opt/immich
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.envResist the urge to hand-roll the compose file from a blog post (including this one). Immich's own release attaches the compose file matching that version, and the project changes internals often enough that third-hand compose files are the top source of broken installs.
Step 2: Edit the .env file
Open .env and set three things:
UPLOAD_LOCATION=/opt/immich/library
DB_PASSWORD=pick_something_alphanumeric
TZ=Europe/LondonTwo footnotes with teeth. UPLOAD_LOCATION is where every photo you ever upload will live, so put it on the volume with the space (this is the line you'd point at mounted bulk storage). And the database password only accepts plain A-Z, a-z and 0-9; special characters break the connection string, a documented quirk that costs new installs an hour of confused log reading. The password never leaves the machine (Postgres isn't exposed publicly), so a long boring alphanumeric string is exactly right.
The IMMICH_VERSION variable defaults to the current major (v3 as I write this). Pinning it to an exact release instead is the conservative move; more on that trade-off in our Immich update guide, because it's really an upgrade-strategy decision.
Step 3: Start it
docker compose up -dFirst run pulls a few gigabytes of images (the machine-learning container carries models), so give it a few minutes, then check all four containers report healthy:
docker compose psThe web interface answers at http://YOUR_SERVER_IP:2283. The first visit runs the welcome flow: create the admin account (this first account owns server administration, treat the password accordingly), confirm storage and you land in an empty library. Port 2283 and what to put in front of it get their own article in the Immich ports guide; short version, for anything beyond a quick test you want a reverse proxy with HTTPS in front, since your phone will be shipping your entire camera roll to this address.
Step 4: Connect the mobile app
Install Immich from the App Store or Play Store, point it at your server URL (the full address with scheme and port, or your proxied HTTPS domain), sign in and enable backup for the albums you want synced. The first backup of a full camera roll is measured in hours and entirely network-bound; leave the phone on wifi and charging overnight and it's done by morning. Photos land in UPLOAD_LOCATION, thumbnails generate, faces start clustering after the ML jobs chew through the library.
Web uploads, album sharing and partner accounts all work out of the box from here. The one setup piece I'd do in week one rather than someday: backups. Immich dumps its database nightly on its own, but the photo files themselves are your responsibility, and a photo library is the least replaceable data most people own.
Verify the install
Four checks and you're done. All containers healthy in docker compose ps. A test photo uploaded through the web UI appears with a thumbnail (proves storage writes and the thumbnail pipeline). The same photo turns up in a smart search for its content a few minutes later (proves the ML container is doing its job). And Administration » Jobs shows queues ticking along rather than piling up errors. Anything failing there usually traces to permissions on UPLOAD_LOCATION or too little RAM for the ML container, in that order.
From here Immich mostly runs itself, with one standing obligation: read the release notes before you update, because the project ships fast and breaking changes are routine housekeeping rather than rare events. That habit, plus the backup, is the entire maintenance story.
We also ship Immich as a 1-click template on the Immich VPS plans if you'd rather start at the welcome screen and skip everything above; either way the mobile app does the rest of the onboarding for you.
