Requirements
This page lists the hardware and software requirements for running Immich.
Environment Variables
To change environment variables, you must recreate the Immich containers.
Config file
Immich's system configuration — everything under Administration > Settings — is normally stored in the database and edited from the web UI. When the IMMICHCONFIGFILE environment variable is set, Immich reads that configuration from a file instead.
3-2-1 backup method
The 3-2-1 method is a widely used rule of thumb for how many copies of data to keep and where to keep them. It originates from photographer Peter Krogh's writing on digital asset management and is now common guidance across the backup industry.
CLIP models
Contextual (smart) search is powered by CLIP models. This page documents the models Immich supports and how they compare, so you can pick the one that fits your hardware and the languages your users search in.
Docker
Immich is distributed as a set of container images and is run with Docker and the Docker Compose plugin. This page describes what Immich requires from Docker.
Exclusion patterns
Exclusion patterns are a feature of external libraries. They are set per library on its Scan Settings page and have no effect on assets uploaded to Immich normally.
EXIF tags
During the Metadata Extraction job, Immich reads metadata from each asset with ExifTool and, for videos, supplements it with stream information from ffprobe. This page lists which tags feed which feature.
Hardware acceleration support
Immich can offload video transcoding and machine learning to a GPU. The two use different backends and have different constraints, listed separately below.
Immich API
Immich exposes a REST API that the web app, mobile app, and CLI all use. Anything those clients can do can be done through the API.
Immich CLI
Immich CLI is a command-line-interface (CLI) that uploads media to an Immich instance. It is available as both an npm package and a Docker image.
Jobs
Immich performs most of its work in background jobs, each with its own queue. The queues are visible at Administration > Job Queues, where they can be watched and manually triggered.
Logging
Immich logs to standard output, so logs are read with docker logs — see Inspect containers and logs. Three environment variables control what is logged and how it is formatted.
OAuth settings
The settings below are configured on the web at Administration > Settings > Authentication. For the steps to register a client application with a provider and turn OAuth on, see Set up OAuth authentication.
Reverse proxy requirements
A custom reverse proxy can sit in front of Immich to handle TLS termination, load balancing, or other advanced features. Any proxy between Immich and the user must meet the requirements below. For configurations that satisfy them, see Set up a reverse proxy.
Server Commands
The immich-server docker image comes preinstalled with an administrative CLI (immich-admin) that supports the commands below.
Storage locations
Immich stores original assets, generated content, database dumps, and the database itself in separate directories. This page describes what each one holds. Some locations depend on whether the storage template is enabled.
Supported Media Formats
Immich supports a variety of image and video formats, the most common of which are outlined here.
System Settings
The admin user can manage settings for the Immich instance here.
Workers
A worker is an independent process inside the immich-server container. Which workers a container runs determines what work it takes on, which is what makes it possible to split responsibilities across containers or machines.
XMP Sidecars
Immich supports XMP sidecar files — external .xmp files that store metadata for an image or video in XML format. During the metadata extraction job Immich will read & import metadata from .xmp files, and during the Sidecar Write job it will write metadata back to .xmp.