Skip to main content

Docker Compose [Recommended]

Docker Compose is the recommended method to run Immich in production. Below are the steps to deploy Immich with Docker Compose.
Immich requires Docker Compose version 2.x.

Step 1 - Download the required files

Create a directory of your choice (e.g. ./immich-app) to hold the docker-compose.yml and .env files.

Move to the directory you created
mkdir ./immich-app
cd ./immich-app

Download docker-compose.yml and example.env, either by running the following commands:

Get docker-compose.yml file
wget -O docker-compose.yml https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml
Get .env file
wget -O .env https://github.com/immich-app/immich/releases/latest/download/example.env
(Optional) Get hwaccel.transcoding.yml file
wget -O hwaccel.transcoding.yml https://github.com/immich-app/immich/releases/latest/download/hwaccel.transcoding.yml
(Optional) Get hwaccel.ml.yml file
wget -O hwaccel.ml.yml https://github.com/immich-app/immich/releases/latest/download/hwaccel.ml.yml

or by downloading from your browser and moving the files to the directory that you created.

Note: If you downloaded the files from your browser, also ensure that you rename example.env to .env.

info

Optionally, you can enable hardware acceleration for machine learning and transcoding. See the Hardware Transcoding and Hardware-Accelerated Machine Learning guides for info on how to set these up.

Step 2 - Populate the .env file with custom values

Example .env content

# You can find documentation for all the supported env variables at https://immich.app/docs/install/environment-variables

# The location where your uploaded files are stored
UPLOAD_LOCATION=./library
# The location where your database files are stored
DB_DATA_LOCATION=./postgres

# To set a timezone, uncomment the next line and change Etc/UTC to a TZ identifier from this list: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List
# TZ=Etc/UTC

# The Immich version to use. You can pin this to a specific version like "v1.71.0"
IMMICH_VERSION=release

# Connection secret for postgres. You should change it to a random password
DB_PASSWORD=postgres

# The values below this line do not need to be changed
###################################################################################
DB_USERNAME=postgres
DB_DATABASE_NAME=immich
  • Populate custom database information if necessary.
  • Populate UPLOAD_LOCATION with your preferred location for storing backup assets.
  • Consider changing DB_PASSWORD to something randomly generated

Step 3 - Start the containers

From the directory you created in Step 1, (which should now contain your customized docker-compose.yml and .env files) run docker compose up -d.

Start the containers using docker compose command
docker compose up -d
Docker version

If you get an error unknown shorthand flag: 'd' in -d, you are probably running the wrong Docker version. (This happens, for example, with the docker.io package in Ubuntu 22.04.3 LTS.) You can correct the problem by apt removeing Ubuntu's docker.io package and installing docker and docker-compose via Docker's official repository.

Note that the correct command really is docker compose, not docker-compose. If you try the latter on vanilla Ubuntu 22.04 it will fail in a different way:

The Compose file './docker-compose.yml' is invalid because:
'name' does not match any of the regexes: '^x-'

See the previous paragraph about installing from the official docker repository.

tip

For more information on how to use the application, please refer to the Post Installation guide.

GitHub Authentication

Downloading container images might require you to authenticate to the GitHub Container Registry (steps here).

Step 4 - Upgrading

Breaking Changes

It is important to follow breaking updates to avoid problems. You can see versions that had breaking changes here.

If IMMICH_VERSION is set, it will need to be updated to the latest or desired version.

When a new version of Immich is released, the application can be upgraded with the following commands, run in the directory with the docker-compose.yml file:

Upgrade Immich
docker compose pull && docker compose up -d
Automatic Updates

Immich is currently under heavy development, which means you can expect breaking changes and bugs. Therefore, we recommend reading the release notes prior to updating and to take special care when using automated tools like Watchtower.