How to Install Immich with Docker Compose

Immich is a self-hosted photo and video backup solution designed as a privacy-first alternative to Google Photos. It offers automatic mobile backups, facial recognition, machine learning-powered search, and a polished web interface — all running on your own hardware, with your data staying entirely under your control. Docker Compose is the only officially supported and recommended installation method for production use, and the setup process is straightforward if you follow each step carefully. This guide walks you through a complete installation on a Linux server from scratch.

Before You Begin

System Requirements

Immich runs several services simultaneously — including a machine learning container for AI features — so it has meaningful resource requirements. The minimum specification is 6GB RAM and 2 CPU cores, though the recommended configuration is 8GB RAM and 4 CPU cores for a smooth experience, particularly if you have a large photo library or multiple users.

One critical requirement that catches many users out: the directory you use for DB_DATA_LOCATION (where PostgreSQL stores its data) must be on a filesystem that supports Unix permissions. Compatible filesystems include EXT4, ZFS, BTRFS, and XFS. If you try to point this at an NTFS or FAT/exFAT partition — common on external drives or NAS shares mounted from Windows — Immich will fail to start. Keep your database storage on a native Linux filesystem.

Docker and Docker Compose

Immich requires the modern Docker Compose plugin — the integrated docker compose command (with a space). The legacy standalone docker-compose binary (with a hyphen) is deprecated and is not supported by Immich. If you are running an older Docker installation, you will need to update before proceeding.

To check whether you have the correct version installed, run:

docker compose version

If this returns a version number, you are good to go. If the command is not found, install Docker using the official method for your distribution. On Ubuntu or Debian:

curl -fsSL https://get.docker.com | sh

This script installs Docker Engine along with the Compose plugin. Once complete, verify both are available:

docker --version
docker compose version

If you want to run Docker commands without sudo, add your user to the docker group and log out and back in:

sudo usermod -aG docker $USER

Installing Immich

Step 1: Create the Immich Directory

Create a dedicated directory for Immich and move into it. Using /opt/immich is a sensible convention for server applications, though any location on a supported filesystem works:

mkdir /opt/immich && cd /opt/immich

Step 2: Download the Official Configuration Files

Immich provides an official docker-compose.yml file and an example environment file. Download both directly from the Immich GitHub releases:

curl -L https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml -o docker-compose.yml

curl -L https://github.com/immich-app/immich/releases/latest/download/example.env -o .env

Do not modify the docker-compose.yml file directly for basic configuration — all user-facing settings are controlled through the .env file.

Step 3: Configure the Environment File

Open the .env file in your editor of choice:

nano .env

There are three key variables to set:

UPLOAD_LOCATION — the path where Immich will store your uploaded photos and videos. A relative path like ./library keeps everything within your /opt/immich directory, which is convenient. For large libraries, you may prefer to point this at a dedicated data drive:

UPLOAD_LOCATION=./library

DB_DATA_LOCATION — where PostgreSQL stores its database files. Remember: this must be on EXT4, ZFS, BTRFS, or XFS. A relative path works well here too:

DB_DATA_LOCATION=./postgres

IMMICH_VERSION — this defaults to release, which always pulls the latest stable version. If you prefer to pin to a specific version for stability and controlled upgrades, set it explicitly, for example:

IMMICH_VERSION=v1.132.3

Leaving it as release is fine for most users. The remaining variables in the file — including the database password — are pre-populated with sensible defaults. You can leave these as-is for a standard installation, though you may wish to change DB_PASSWORD to something unique before going live.

Save and close the file when done.

Step 4: Start Immich

With the configuration in place, start all Immich services in detached mode:

docker compose up -d

Docker will pull the required images and start four services: immich-server (the main application and API), immich-machine-learning (handles facial recognition and smart search), postgres (the PostgreSQL database), and redis (used for job queuing and caching). The first run will take a few minutes as the images download.

Once complete, check that all containers are running:

docker compose ps

All four services should show a status of Up. If any container has exited, inspect the logs to diagnose the issue:

docker compose logs immich-server

Accessing Immich

Once all containers are running, open a browser and navigate to your server’s IP address on port 2283:

http://[server-ip]:2283

Replace [server-ip] with the actual IP address of your server. If you are accessing it from the same machine, http://localhost:2283 also works.

Initial Setup

Creating the Admin Account

The first user to register on a fresh Immich installation automatically becomes the administrator. Navigate to the web interface and complete the registration form with your name, email address, and password. This admin account has full access to all settings, user management, and library configuration.

Do not share the admin credentials. If you want to give others access, create separate user accounts through the admin panel.

Adding Additional Users

Once logged in as admin, navigate to Administration > Users to create accounts for other members of your household or team. Each user gets their own library, upload quota (optional), and backup storage allocation. Users can also be granted admin privileges if required.

Connecting the Mobile App

Immich has official apps for both iOS and Android that handle automatic background photo backups. Install the app, then enter your server address (including the port, e.g. http://192.168.1.100:2283), and log in with your credentials. From the app settings, configure which albums or folders to back up, and whether to back up over Wi-Fi only or also on mobile data.

For remote access outside your home network, you will need to either expose port 2283 through your router or, preferably, set up a reverse proxy with SSL termination using Nginx or Caddy and a domain name.

Keeping Immich Updated

Updating Immich is straightforward. From your /opt/immich directory, pull the latest images and restart the stack:

cd /opt/immich
docker compose pull && docker compose up -d

If you have pinned IMMICH_VERSION in your .env file, update that value first before running the pull command. Always check the Immich release notes before upgrading — occasional releases include database migrations or breaking changes that warrant a brief review. Full documentation, including advanced configuration options, is available at docs.immich.app/install/docker-compose.

Related Immich Guides

• Immich: The Complete Self-Hosted Google Photos Alternative
• What Is Immich? The Self-Hosted Google Photos Alternative
• Immich vs Google Photos: Is Self-Hosting Worth It?
• How to Set Up Immich Mobile Backup on iPhone and Android
• How to Run Immich on Proxmox: LXC Container Setup
• How to Put Immich Behind a Reverse Proxy with SSL
• Immich Hardware Requirements: Raspberry Pi, NUC, or NAS?
• Immich Face Recognition and Smart Search: How to Enable It
• How to Back Up Immich: Protecting Your Photo Library
• Immich vs PhotoPrism vs Piwigo: Best Self-Hosted Photo App?