Environment Variables

caution

To change environment variables, you must recreate the Immich containers. Just restarting the containers does not replace the environment within the container!

In order to recreate the container using docker compose, run docker compose up -d. In most cases docker will recognize that the .env file has changed and recreate the affected containers. If this should not work, try running docker compose up -d --force-recreate.

Docker Compose

Variable	Description	Default	Containers
IMMICH_VERSION	Image tags	release	server, machine learning
UPLOAD_LOCATION	Host Path for uploads		server
DB_DATA_LOCATION	Host Path for Postgres database		database

tip

These environment variables are used by the docker-compose.yml file and do NOT affect the containers directly.

Supported filesystems

The Immich Postgres database (DB_DATA_LOCATION) must be located on a filesystem that supports user/group ownership and permissions (EXT2/3/4, ZFS, APFS, BTRFS, XFS, etc.). It will not work on any filesystem formatted in NTFS or ex/FAT/32. It will not work in WSL (Windows Subsystem for Linux) when using a mounted host directory (commonly under /mnt). If this is an issue, you can change the bind mount to a Docker volume instead.

Regardless of filesystem, it is not recommended to use a network share for your database location due to performance and possible data loss issues.

General

Variable	Description	Default	Containers	Workers
TZ	Timezone		server	microservices
IMMICH_ENV	Environment (production, development)	production	server, machine learning	api, microservices
IMMICH_LOG_LEVEL	Log Level (verbose, debug, log, warn, error)	log	server, machine learning	api, microservices
IMMICH_MEDIA_LOCATION	Media Location	./upload*1	server	api, microservices
IMMICH_CONFIG_FILE	Path to config file		server	api, microservices
IMMICH_WEB_ROOT	Path of root index.html	/usr/src/app/www	server	api
IMMICH_REVERSE_GEOCODING_ROOT	Path of reverse geocoding dump directory	/usr/src/resources	server	microservices
NO_COLOR	Set to true to disable color-coded log output	false	server, machine learning
CPU_CORES	Amount of cores available to the immich server	auto-detected cpu core count	server
IMMICH_API_METRICS_PORT	Port for the OTEL metrics	8081	server	api
IMMICH_MICROSERVICES_METRICS_PORT	Port for the OTEL metrics	8082	server	microservices

*1: With the default WORKDIR of /usr/src/app, this path will resolve to /usr/src/app/upload. It only need to be set if the Immich deployment method is changing.

tip

TZ should be set to a TZ identifier from this list. For example, TZ="Etc/UTC".

TZ is used by exiftool as a fallback in case the timezone cannot be determined from the image metadata. It is also used for logfile timestamps and cron job execution.

Workers

Variable	Description	Default	Containers
IMMICH_WORKERS_INCLUDE	Only run these workers.		server
IMMICH_WORKERS_EXCLUDE	Do not run these workers. Matches against default workers, or IMMICH_WORKERS_INCLUDE if specified.		server

info

Information on the current workers can be found here.

Ports

Variable	Description	Default
IMMICH_HOST	Listening host	0.0.0.0
IMMICH_PORT	Listening port	3001 (server), 3003 (machine learning)

Database

Variable	Description	Default	Containers
DB_URL	Database URL		server
DB_HOSTNAME	Database Host	database	server
DB_PORT	Database Port	5432	server
DB_USERNAME	Database User	postgres	server, database*1
DB_PASSWORD	Database Password	postgres	server, database*1
DB_DATABASE_NAME	Database Name	immich	server, database*1
DB_VECTOR_EXTENSION*2	Database Vector Extension (one of [pgvector, pgvecto.rs])	pgvecto.rs	server
DB_SKIP_MIGRATIONS	Whether to skip running migrations on startup (one of [true, false])	false	server

*1: The values of DB_USERNAME, DB_PASSWORD, and DB_DATABASE_NAME are passed to the Postgres container as the variables POSTGRES_USER, POSTGRES_PASSWORD, and POSTGRES_DB in docker-compose.yml.

*2: This setting cannot be changed after the server has successfully started up.

info

All DB_ variables must be provided to all Immich workers, including api and microservices.

DB_URL must be in the format postgresql://immichdbusername:immichdbpassword@postgreshost:postgresport/immichdatabasename. You can require SSL by adding ?sslmode=require to the end of the DB_URL string, or require SSL and skip certificate verification by adding ?sslmode=require&sslmode=no-verify.

When DB_URL is defined, the DB_HOSTNAME, DB_PORT, DB_USERNAME, DB_PASSWORD and DB_DATABASE_NAME database variables are ignored.

Redis

Variable	Description	Default	Containers
REDIS_URL	Redis URL		server
REDIS_SOCKET	Redis Socket		server
REDIS_HOSTNAME	Redis Host	redis	server
REDIS_PORT	Redis Port	6379	server
REDIS_USERNAME	Redis Username		server
REDIS_PASSWORD	Redis Password		server
REDIS_DBINDEX	Redis DB Index	0	server

info

All REDIS_ variables must be provided to all Immich workers, including api and microservices.

REDIS_URL must start with ioredis:// and then include a base64 encoded JSON string for the configuration. More info can be found in the upstream ioredis documentation.

When REDIS_URL or REDIS_SOCKET are defined, the REDIS_HOSTNAME, REDIS_PORT, REDIS_USERNAME, REDIS_PASSWORD, and REDIS_DBINDEX variables are ignored.

Redis (Sentinel) URL example JSON before encoding:

JSON

{
  "sentinels": [
    {
      "host": "redis-sentinel-node-0",
      "port": 26379
    },
    {
      "host": "redis-sentinel-node-1",
      "port": 26379
    },
    {
      "host": "redis-sentinel-node-2",
      "port": 26379
    }
  ],
  "name": "redis-sentinel"
}

Machine Learning

Variable	Description	Default	Containers
MACHINE_LEARNING_MODEL_TTL	Inactivity time (s) before a model is unloaded (disabled if <= 0)	300	machine learning
MACHINE_LEARNING_MODEL_TTL_POLL_S	Interval (s) between checks for the model TTL (disabled if <= 0)	10	machine learning
MACHINE_LEARNING_CACHE_FOLDER	Directory where models are downloaded	/cache	machine learning
MACHINE_LEARNING_REQUEST_THREADS*1	Thread count of the request thread pool (disabled if <= 0)	number of CPU cores	machine learning
MACHINE_LEARNING_MODEL_INTER_OP_THREADS	Number of parallel model operations	1	machine learning
MACHINE_LEARNING_MODEL_INTRA_OP_THREADS	Number of threads for each model operation	2	machine learning
MACHINE_LEARNING_WORKERS*2	Number of worker processes to spawn	1	machine learning
MACHINE_LEARNING_WORKER_TIMEOUT	Maximum time (s) of unresponsiveness before a worker is killed	120	machine learning
MACHINE_LEARNING_PRELOAD__CLIP	Name of a CLIP model to be preloaded and kept in cache		machine learning
MACHINE_LEARNING_PRELOAD__FACIAL_RECOGNITION	Name of a facial recognition model to be preloaded and kept in cache		machine learning

*1: It is recommended to begin with this parameter when changing the concurrency levels of the machine learning service and then tune the other ones.

*2: Since each process duplicates models in memory, changing this is not recommended unless you have abundant memory to go around.

info

Other machine learning parameters can be tuned from the admin UI.

Prometheus

Variable	Description	Default	Containers	Workers
IMMICH_METRICS*1	Toggle all metrics (one of [true, false])		server	api, microservices
IMMICH_API_METRICS	Toggle metrics for endpoints and response times (one of [true, false])		server	api, microservices
IMMICH_HOST_METRICS	Toggle metrics for CPU and memory utilization for host and process (one of [true, false])		server	api, microservices
IMMICH_IO_METRICS	Toggle metrics for database queries, image processing, etc. (one of [true, false])		server	api, microservices
IMMICH_JOB_METRICS	Toggle metrics for jobs and queues (one of [true, false])		server	api, microservices

*1: Overridden for a metric group when its corresponding environmental variable is set.

Docker Secrets

The following variables support the use of Docker secrets for additional security.

To use any of these, replace the regular environment variable with the equivalent _FILE environment variable. The value of the _FILE variable should be set to the path of a file containing the variable value.

Regular Variable	Equivalent Docker Secrets '_FILE' Variable
DB_HOSTNAME	DB_HOSTNAME_FILE*1
DB_DATABASE_NAME	DB_DATABASE_NAME_FILE*1
DB_USERNAME	DB_USERNAME_FILE*1
DB_PASSWORD	DB_PASSWORD_FILE*1
DB_URL	DB_URL_FILE*1
REDIS_PASSWORD	REDIS_PASSWORD_FILE*2

*1: See the official documentation for details on how to use Docker Secrets in the Postgres image.

*2: See this comment for an example of how to use use a Docker secret for the password in the Redis container.