Skip to main content

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​

VariableDescriptionDefaultContainers
IMMICH_VERSIONImage tagsreleaseserver, machine learning
UPLOAD_LOCATIONHost Path for uploadsserver
DB_DATA_LOCATIONHost Path for Postgres databasedatabase
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​

VariableDescriptionDefaultContainersWorkers
TZTimezoneservermicroservices
IMMICH_ENVEnvironment (production, development)productionserver, machine learningapi, microservices
IMMICH_LOG_LEVELLog Level (verbose, debug, log, warn, error)logserver, machine learningapi, microservices
IMMICH_MEDIA_LOCATIONMedia Location./upload*1serverapi, microservices
IMMICH_CONFIG_FILEPath to config fileserverapi, microservices
NO_COLORSet to true to disable color-coded log outputfalseserver, machine learning
CPU_CORESAmount of cores available to the immich serverauto-detected cpu core countserver
IMMICH_API_METRICS_PORTPort for the OTEL metrics8081serverapi
IMMICH_MICROSERVICES_METRICS_PORTPort for the OTEL metrics8082servermicroservices
IMMICH_PROCESS_INVALID_IMAGESWhen true, generate thumbnails for invalid imagesservermicroservices
IMMICH_TRUSTED_PROXIESList of comma separated IPs set as trusted proxiesserverapi

*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​

VariableDescriptionDefaultContainers
IMMICH_WORKERS_INCLUDEOnly run these workers.server
IMMICH_WORKERS_EXCLUDEDo 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​

VariableDescriptionDefault
IMMICH_HOSTListening host0.0.0.0
IMMICH_PORTListening port3001 (server), 3003 (machine learning)

Database​

VariableDescriptionDefaultContainers
DB_URLDatabase URLserver
DB_HOSTNAMEDatabase Hostdatabaseserver
DB_PORTDatabase Port5432server
DB_USERNAMEDatabase Userpostgresserver, database*1
DB_PASSWORDDatabase Passwordpostgresserver, database*1
DB_DATABASE_NAMEDatabase Nameimmichserver, database*1
DB_VECTOR_EXTENSION*2Database Vector Extension (one of [pgvector, pgvecto.rs])pgvecto.rsserver
DB_SKIP_MIGRATIONSWhether to skip running migrations on startup (one of [true, false])falseserver

*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​

VariableDescriptionDefaultContainers
REDIS_URLRedis URLserver
REDIS_SOCKETRedis Socketserver
REDIS_HOSTNAMERedis Hostredisserver
REDIS_PORTRedis Port6379server
REDIS_USERNAMERedis Usernameserver
REDIS_PASSWORDRedis Passwordserver
REDIS_DBINDEXRedis DB Index0server
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​

VariableDescriptionDefaultContainers
MACHINE_LEARNING_MODEL_TTLInactivity time (s) before a model is unloaded (disabled if <= 0)300machine learning
MACHINE_LEARNING_MODEL_TTL_POLL_SInterval (s) between checks for the model TTL (disabled if <= 0)10machine learning
MACHINE_LEARNING_CACHE_FOLDERDirectory where models are downloaded/cachemachine learning
MACHINE_LEARNING_REQUEST_THREADS*1Thread count of the request thread pool (disabled if <= 0)number of CPU coresmachine learning
MACHINE_LEARNING_MODEL_INTER_OP_THREADSNumber of parallel model operations1machine learning
MACHINE_LEARNING_MODEL_INTRA_OP_THREADSNumber of threads for each model operation2machine learning
MACHINE_LEARNING_WORKERS*2Number of worker processes to spawn1machine learning
MACHINE_LEARNING_WORKER_TIMEOUTMaximum time (s) of unresponsiveness before a worker is killed120 (300 if using OpenVINO image)machine learning
MACHINE_LEARNING_PRELOAD__CLIPName of a CLIP model to be preloaded and kept in cachemachine learning
MACHINE_LEARNING_PRELOAD__FACIAL_RECOGNITIONName of a facial recognition model to be preloaded and kept in cachemachine learning
MACHINE_LEARNING_ANNEnable ARM-NN hardware acceleration if supportedTruemachine learning
MACHINE_LEARNING_ANN_FP16_TURBOExecute operations in FP16 precision: increasing speed, reducing precision (applies only to ARM-NN)Falsemachine learning
MACHINE_LEARNING_ANN_TUNING_LEVELARM-NN GPU tuning level (1: rapid, 2: normal, 3: exhaustive)2machine 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​

VariableDescriptionDefaultContainersWorkers
IMMICH_METRICS*1Toggle all metrics (one of [true, false])serverapi, microservices
IMMICH_API_METRICSToggle metrics for endpoints and response times (one of [true, false])serverapi, microservices
IMMICH_HOST_METRICSToggle metrics for CPU and memory utilization for host and process (one of [true, false])serverapi, microservices
IMMICH_IO_METRICSToggle metrics for database queries, image processing, etc. (one of [true, false])serverapi, microservices
IMMICH_JOB_METRICSToggle metrics for jobs and queues (one of [true, false])serverapi, 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 VariableEquivalent Docker Secrets '_FILE' Variable
DB_HOSTNAMEDB_HOSTNAME_FILE*1
DB_DATABASE_NAMEDB_DATABASE_NAME_FILE*1
DB_USERNAMEDB_USERNAME_FILE*1
DB_PASSWORDDB_PASSWORD_FILE*1
DB_URLDB_URL_FILE*1
REDIS_PASSWORDREDIS_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.