Immich

Here is a quick, no-choices path to install Immich and take it for a test drive. Once you've tried it, you might use one of the many other ways to install and use it.

Requirements#

• A system with at least 6GB of RAM and 2 CPU cores.
• Docker

For a more detailed list of requirements, see the requirements page.

Hardware#

• OS: Recommended Linux or *nix 64-bit operating system (Ubuntu, Debian, etc).
  • Non-Linux OSes tend to provide a poor Docker experience and are strongly discouraged. Our ability to assist with setup or troubleshooting on non-Linux OSes will be severely reduced. If you still want to try to use a non-Linux OS, you can set it up as follows:
    • Windows: Docker Desktop on Windows or WSL 2.
    • macOS: Docker Desktop on Mac.
  • Immich runs well in a virtualized environment when running in a full virtual machine. The use of Docker in LXC containers is not recommended, but may be possible for advanced users. If you have issues, we recommend that you switch to a supported VM deployment.
• RAM: Minimum 6GB, recommended 8GB.
• CPU: Minimum 2 cores, recommended 4 cores.
  • Immich runs on the amd64 and arm64 platforms. Since v3, the machine learning container on amd64 requires the >= x86-64-v2 microarchitecture level. Most CPUs released since ~2012 support this microarchitecture. If you are using a virtual machine, ensure you have selected a supported microarchitecture. If you are unable to support this instruction set, the last version to support x86-64-v1 is v2.7.5. Note that this release is no longer supported, and you must run a matching immich-server version.
• Storage: Recommended Unix-compatible filesystem (EXT4, ZFS, APFS, etc.) with support for user/group ownership and permissions.
  • The generation of thumbnails and transcoded video can increase the size of the photo library by 10-20% on average.

Software#

Immich requires Docker with the Docker Compose plugin:

• Docker Engine: This CLI variant is designed for Linux servers (or Windows via WSL2).
• Docker Desktop: This GUI variant is not recommended for Linux, but is available for Windows or macOS.

The Compose plugin will be installed by both Docker Engine and Desktop by following the linked installation guides; it can also be separately installed.

Set up the server#

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.

mkdir ./immich-app
cd ./immich-app

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

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

You can alternatively download these two files from your browser and move them to the directory that you created, in which case ensure that you rename example.env to .env.

Step 2 - Populate the .env file with custom values#

# You can find documentation for all the supported env variables at https://docs.immich.app/install/environment-variables
 
# The location where your uploaded files are stored
UPLOAD_LOCATION=./library
 
# The location where your database files are stored. Network shares are not supported for the database
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 "v2.1.0"
IMMICH_VERSION=v3
 
# Connection secret for postgres. You should change it to a random password
# Please use only the characters `A-Za-z0-9`, without special characters or spaces
DB_PASSWORD=postgres
 
# The values below this line do not need to be changed
###################################################################################
DB_USERNAME=postgres
DB_DATABASE_NAME=immich

• Populate UPLOAD_LOCATION with your preferred location for storing backup assets. It should be a new directory on the server with enough free space.
• Consider changing DB_PASSWORD to a custom value. Postgres is not publicly exposed, so this password is only used for local authentication. To avoid issues with Docker parsing this value, it is best to use only the characters A-Za-z0-9. pwgen is a handy utility for this.
• Set your timezone by uncommenting the TZ= line.
• Populate custom database information if necessary.

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 the following command to start Immich as a background service:

docker compose up -d

Try the web app#

The first user to register will be the admin user. The admin user will be able to add other users to the application.

To register for the admin user, access the web application at http://<machine-ip-address>:2283 and click on the Getting Started button.

Follow the prompts to register as the admin user and log in to the application.

Try uploading a picture from your browser.

Review the database backup and restore process#

Immich has built-in database backups. You can refer to the database backup for more information.

Setup Server Backups#

Now that you have imported some pictures, you should setup server backups to preserve your memories. You can do so by following our backup guide.