immich/docs/docs/install/environment-variables.md

sidebar_position

sidebar_position
90

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. :::

General

Variable	Description	Default	Containers	Workers
TZ	Timezone	*1	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 inside the container ⚠️You probably shouldn't set this*2⚠️	./upload*3	server	api, microservices
IMMICH_CONFIG_FILE	Path to config file		server	api, 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
IMMICH_PROCESS_INVALID_IMAGES	When true, generate thumbnails for invalid images		server	microservices
IMMICH_TRUSTED_PROXIES	List of comma separated IPs set as trusted proxies		server	api
IMMICH_IGNORE_MOUNT_CHECK_ERRORS	See System Integrity		server	api, microservices

*1: 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.

*2: This path is where the Immich code looks for the files, which is internal to the docker container. Setting it to a path on your host will certainly break things, you should use the UPLOAD_LOCATION variable instead.

*3: 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.

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	2283 (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_HTTP_KEEPALIVE_TIMEOUT_S*3	HTTP Keep-alive time in seconds	2	machine learning
MACHINE_LEARNING_WORKER_TIMEOUT	Maximum time (s) of unresponsiveness before a worker is killed	120 (300 if using OpenVINO)	machine learning
MACHINE_LEARNING_PRELOAD__CLIP__TEXTUAL	Comma-separated list of (textual) CLIP model(s) to preload and cache		machine learning
MACHINE_LEARNING_PRELOAD__CLIP__VISUAL	Comma-separated list of (visual) CLIP model(s) to preload and cache		machine learning
MACHINE_LEARNING_PRELOAD__FACIAL_RECOGNITION__RECOGNITION	Comma-separated list of (recognition) facial recognition model(s) to preload and cache		machine learning
MACHINE_LEARNING_PRELOAD__FACIAL_RECOGNITION__DETECTION	Comma-separated list of (detection) facial recognition model(s) to preload and cache		machine learning
MACHINE_LEARNING_ANN	Enable ARM-NN hardware acceleration if supported	True	machine learning
MACHINE_LEARNING_ANN_FP16_TURBO	Execute operations in FP16 precision: increasing speed, reducing precision (applies only to ARM-NN)	False	machine learning
MACHINE_LEARNING_ANN_TUNING_LEVEL	ARM-NN GPU tuning level (1: rapid, 2: normal, 3: exhaustive)	2	machine learning
MACHINE_LEARNING_DEVICE_IDS*4	Device IDs to use in multi-GPU environments	0	machine learning
MACHINE_LEARNING_MAX_BATCH_SIZE__FACIAL_RECOGNITION	Set the maximum number of faces that will be processed at once by the facial recognition model	None (1 if using OpenVINO)	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.

*3: For scenarios like HPA in K8S. https://github.com/immich-app/immich/discussions/12064

*4: Using multiple GPUs requires MACHINE_LEARNING_WORKERS to be set greater than 1. A single device is assigned to each worker in round-robin priority.

:::info

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

:::

Prometheus

Variable	Description	Default	Containers	Workers
IMMICH_TELEMETRY_INCLUDE	Collect these telemetries. List of host, api, io, repo, job. Note: You can also specify all to enable all		server	api, microservices
IMMICH_TELEMETRY_EXCLUDE	Do not collect these telemetries. List of host, api, io, repo, job		server	api, microservices

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.