How to Self-Host Immich and Access Your Photo Library from Anywhere

Why Immich Has Become the Self-Hosting Community's Go-To Photos App

Immich started in February 2022 as a personal project and grew to over 90,000 GitHub stars by early 2026, making it one of the fastest-growing self-hosted applications ever built. The reason is straightforward: it is the first self-hosted photo manager that actually feels like a consumer product rather than a technical experiment.

What Gets Installed: The Four Containers

Immich runs as four Docker containers that work together. Understanding what each one does matters when things go wrong.

Requirements Before You Start

Step 1: Install Docker Engine

Install Docker Engine from Docker's official repository, not from your Linux distribution's package manager. The distribution's docker.io package is often outdated and causes known issues with Immich's compose file format.

# Remove any old Docker packages from the distro
sudo apt remove docker docker-engine docker.io containerd runc 2>/dev/null

# Install prerequisites
sudo apt update
sudo apt install ca-certificates curl gnupg -y

# Add Docker's official GPG key
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
  sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

# Add Docker's repository
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list

# Install Docker Engine and Compose plugin
sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-compose-plugin -y

# Allow your user to run docker without sudo
sudo usermod -aG docker $USER
newgrp docker

Verify the installation:

docker --version && docker compose version

Docker version 27.5.1, build 9f9e405
Docker Compose version v2.33.1

Step 2: Download the Official Compose Files

The official installation method is to download the compose file and environment file directly from the latest Immich release. Do not manually copy compose files from blog posts or tutorials — the files change between releases and an outdated compose file is the most common cause of installation problems.

mkdir ~/immich-app
cd ~/immich-app

# Download the official docker-compose.yml from the latest release
wget -O docker-compose.yml \
  https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml

# Download the example .env file
wget -O .env \
  https://github.com/immich-app/immich/releases/latest/download/example.env

Step 3: Configure the Environment File

Open the .env file and configure the three required variables:

nano .env

# Where your uploaded photos and videos are stored on the host.
# This directory will grow as you add photos. Point it to wherever
# you have storage space. Can be on a NAS or external drive.
UPLOAD_LOCATION=./library

# Where the PostgreSQL database files are stored on the host.
# MUST be on a local disk. NFS is not supported.
# SSD recommended for better performance.
DB_DATA_LOCATION=./postgres

# Set your timezone for correct timestamps. Examples:
# Europe/Istanbul, America/New_York, Asia/Tokyo
# Full list: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
TZ=Europe/Istanbul

# The Immich version to use. "v2" pins to the current major version
# and receives all 2.x.x updates. To pin to a specific version
# for controlled upgrades, use a tag like "v2.5.6".
IMMICH_VERSION=v2

# Database password. Use only A-Za-z0-9 characters to avoid
# Docker parsing issues with special characters.
# This password is only used for local container communication —
# the database is never exposed to the internet.
DB_PASSWORD=useAStrongRandomPasswordHere

# Do not change these unless you have a specific reason to.
DB_USERNAME=postgres
DB_DATABASE_NAME=immich

The only required changes are:

Step 4: Storage Type Optimization (SSD vs HDD)

Immich's custom PostgreSQL image has two different performance configurations built in — one optimized for SSDs and one for HDDs. The difference is in how PostgreSQL handles I/O concurrency: SSDs benefit from parallel I/O, while HDDs perform better with sequential access patterns.

By default, Immich assumes SSD storage. If your database is on a spinning disk or a slow NAS-attached volume, add this to the database section of your docker-compose.yml:

    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_USER: ${DB_USERNAME}
      POSTGRES_DB: ${DB_DATABASE_NAME}
      POSTGRES_INITDB_ARGS: '--data-checksums'
      DB_STORAGE_TYPE: 'HDD'   # add this line if your DB is on HDD

Step 5: Start the Containers

docker compose up -d

[+] Running 5/5
 ✔ Network immich_default                    Created
 ✔ Container immich_redis                    Started
 ✔ Container immich_postgres                 Started
 ✔ Container immich_machine_learning         Started
 ✔ Container immich_server                   Started

Wait about 60 to 90 seconds for all containers to finish initializing. The first startup takes longer than subsequent ones because the database schema is being created and initial migrations are running. Check that everything is healthy:

docker compose ps

NAME                       STATUS
immich_postgres            running (healthy)
immich_redis               running (healthy)
immich_machine_learning    running (healthy)
immich_server              running (healthy)

All four containers should show running (healthy). If immich_server shows running (health: starting), wait another minute and check again — it performs a health check on startup that takes time to pass. If any container shows exited, check its logs:

docker compose logs immich_server --tail=50

Step 6: Create Your Admin Account

Open your browser and navigate to http://localhost:2283 (or the server's local IP address on port 2283 if you are accessing it from another device on your network).

On first access, you are taken directly to the account creation screen. Enter a name, email, and strong password for your admin account. This first account automatically receives administrator privileges.

After logging in, visit the Administration panel (top right menu) to review the default settings before adding any content:

Step 7: Set Up the Mobile App for Automatic Backup

Install the Immich app on your phone (available for iOS and Android). When you open it for the first time, it will ask for a server URL. For local network access, enter your server's local IP address and port: http://192.168.1.45:2283. After setting up remote access with Localtonet, you will update this to your public HTTPS URL.

After logging in, go to the app settings and enable Background Backup. The app will upload your existing photo library in the background and continue uploading new photos automatically as you take them, on Wi-Fi only by default (configurable to also use mobile data).

Step 8: Expose Immich to the Internet with Localtonet

For automatic mobile backup to work when you are away from home, and for remote access to your photo library from any device, Immich needs a public HTTPS URL. Localtonet provides this without port forwarding, a static IP, or a domain name.

Install and authenticate Localtonet

Download Localtonet for your platform from localtonet.com, install it on the same machine running Immich, and authenticate with your token from the Localtonet dashboard.

Create an HTTP tunnel to port 2283

In the Localtonet dashboard, create a new tunnel:

Update the .env with your public URL

Immich needs to know its own public URL to generate correct links in shared album emails and API responses. Add this line to your .env file:

IMMICH_SERVER_URL=https://myphotos.localto.net

Restart the server container to apply the change:

docker compose restart immich_server

Navigate to https://myphotos.localto.net from any device. You should see the Immich login page over HTTPS. Localtonet provides the TLS certificate automatically.

Update the mobile app to use the public URL

In the Immich mobile app, go to Settings and update the server URL from the local IP address to your Localtonet public URL: https://myphotos.localto.net. The app will now back up photos over the internet when you are away from home, and continue to use the same URL when on your local network.

Backup and Restore

Immich v2.5.0 introduced a built-in database backup system. The server automatically creates database backups on a configurable schedule (default: daily). You can manage backups from the web UI at Administration → Maintenance, or configure the backup path in your .env file.

There are two things to back up:

To trigger a manual database backup from the command line:

docker compose exec immich_postgres pg_dumpall \
  --clean --if-exists --username=postgres | \
  gzip > ~/immich-db-backup-$(date +%Y%m%d).sql.gz

To restore from a backup (on a fresh installation with the same configuration):

# Stop immich_server and immich_machine_learning first
docker compose stop immich_server immich_machine_learning

# Restore database
gunzip < ~/immich-db-backup-20260210.sql.gz | \
  docker compose exec -T immich_postgres psql \
  --username=postgres

# Restart everything
docker compose start

Keeping Immich Up to Date

Immich releases updates frequently. Since IMMICH_VERSION=v2 does not auto-update (it pins to the major version, not "latest"), you need to run an update manually:

# Make a database backup first
docker compose exec immich_postgres pg_dumpall \
  --clean --if-exists --username=postgres | \
  gzip > ~/immich-backup-before-update.sql.gz

# Pull new images
docker compose pull

# Restart with new images (runs database migrations automatically)
docker compose up -d

Hardware Acceleration for Faster Thumbnails and ML

By default, Immich uses the CPU for all video transcoding and machine learning inference. On hardware with a compatible GPU or NPU, enabling acceleration dramatically reduces the time it takes to process a large library import.

To enable hardware acceleration, uncomment the relevant extends section in docker-compose.yml and set the service type. For example, for NVIDIA GPU transcoding:

  immich-server:
    extends:
      file: hwaccel.transcoding.yml
      service: nvenc   # set to: nvenc, quicksync, rkmpp, vaapi, or vaapi-wsl

The hwaccel.transcoding.yml and hwaccel.ml.yml files are downloaded alongside the main compose file. Full documentation is at docs.immich.app/features/ml-hardware-acceleration.

Common Problems and Solutions

Frequently Asked Questions