Skip to main content

Environment variables

Environment variables override YAML and Settings. Use them to keep a deployment's settings fixed. The UI shows which variable controls a setting.

.env and example.env​

Docker Compose reads .env for substitution in the Compose file. It does not pass every line to the container. The service's environment: block must name the variable. Every variable in the shipped example.env is already wired up.

IMMICH_URL=http://192.168.1.10:2283
IMMICH_API_KEY=your-api-key
TZ=Etc/UTC

The shipped .env has no home coordinates. Set them in Settings, or add them to the app's environment: block in docker-compose.yml:

IMMICH_MEMORIES_TRIPS__HOMEBASE_LATITUDE: "50.8503"
IMMICH_MEMORIES_TRIPS__HOMEBASE_LONGITUDE: "4.3517"

After an edit:

docker compose up -d

restart does not reload environment variables. For another setting, add it to environment::

IMMICH_MEMORIES_UPLOAD__ENABLED: "true"

The variables you are most likely to set​

VariablePurpose
IMMICH_URL, IMMICH_API_KEYRequired Immich connection
IMMICH_MEMORIES_IMMICH__PUBLIC_URLOptional: the Immich address your browser opens, for the links the app shows. Unset uses IMMICH_URL; add it to environment: only when you set it. Requests never use it
IMMICH_MEMORIES_TRIPS__HOMEBASE_LATITUDE, IMMICH_MEMORIES_TRIPS__HOMEBASE_LONGITUDEHome coordinates for trips and public holidays
TZDaily timer and log timezone
IMMICH_MEMORIES_AUTH_USERNAME, IMMICH_MEMORIES_AUTH_PASSWORDSet both to choose the Basic sign-in yourself instead of the generated password (password: 12+ characters, or startup warns); shipped .env support
IMMICH_MEMORIES_STORAGE_SECRETOptional session signing key, generated when unset; 32+ random characters (openssl rand -hex 32) or the app refuses to start
IMMICH_MEMORIES_SECRET_KEYEncrypt credentials saved in Settings; shipped .env support
IMMICH_MEMORIES_UPLOAD__ENABLED, IMMICH_MEMORIES_UPLOAD__ALBUM_NAMEUpload CLI/daily films; add to environment:
IMMICH_MEMORIES_DEPLOYMENT_TIERThe deployment's tier: auto, basic, gpu or full (Compose .env: TIER)
IMMICH_MEMORIES_DATABASE_URLOptional PostgreSQL store; set only in the PostgreSQL and maximalist Compose files

For service setup, use the reader, caption, inference, render or music guide. Each gives the variables that service needs.

The pattern​

Every config key has the form IMMICH_MEMORIES_<SECTION>__<FIELD>: double underscores between levels, with no ADVANCED prefix, even for YAML sections under advanced:.

IMMICH_MEMORIES_OUTPUT__RESOLUTION=1080p
IMMICH_MEMORIES_TITLE_SCREENS__FADE_COLOR=black
IMMICH_MEMORIES_EDITORIAL__PREPARATION__CAPTION_BASE_URL=http://captioner:8092/v1

Lists and dictionaries take JSON:

IMMICH_MEMORIES_AUTH__ALLOWED_EMAILS='["me@example.com"]'
IMMICH_MEMORIES_ANALYSIS__EXCLUDE_FILENAME_PATTERNS='["RingVideo_*", "Screenshot*"]'

Setting a list replaces it. Copy any defaults you want to keep. Find field names/defaults in the config reference.

Shorthands​

IMMICH_URL/IMMICH_API_KEY override the corresponding nested variables. To point one command at another Immich, pass -e IMMICH_URL=... (for example docker compose exec -e IMMICH_URL=http://other:2283 ...): that one wins. IMMICH_MEMORIES_IMMICH__URL silently loses to an IMMICH_URL that is set, and the shipped Compose file always sets it. The Basic-auth shortcuts only activate when both values are present. Without them, sign-in is on and the first start generates a password (where to find it). IMMICH_MEMORIES_AUTH__ENABLED=false runs with no sign-in.

IMMICH_MEMORIES_DATABASE_URL and IMMICH_MEMORIES_DATABASE_SCHEMA win over the nested DATABASE__URL and DATABASE__SCHEMA variables. immich-memories config show database shows the store location actually in use, with credentials masked.

OPENAI_API_KEY and ANTHROPIC_API_KEY are different: a resolved key already in llm.api_key (from YAML, stored settings or the nested variable) wins over those generic shortcuts. To replace it explicitly, use IMMICH_MEMORIES_LLM__API_KEY. The caption server needs its own IMMICH_MEMORIES_EDITORIAL__PREPARATION__CAPTION_API_KEY.

The exception reference lists all shortcuts and process variables.

The secret key​

Set IMMICH_MEMORIES_SECRET_KEY to save encrypted credentials from Settings or the CLI. It is not the session signing key. Generate and keep it. Keys supplied only through .env or YAML do not need database encryption.

Precedence​

Environment variables win over config.yaml, with no warning when they disagree. That includes the ones the image sets itself: IMMICH_MEMORIES_OUTPUT__DIRECTORY=/app/output. An output.directory: /output in your config is ignored, and films land in /app/output, which is inside the container's writable layer unless a volume is mounted there. Mount your output volume at /app/output, or set IMMICH_MEMORIES_OUTPUT__DIRECTORY to the path you mounted.

Command flags win for that command, followed by the configuration source order. The generic LLM key shorthands above are the exception to environment-first precedence.

Compute tier​

A deployment sets its tier with IMMICH_MEMORIES_DEPLOYMENT_TIER (auto, basic, gpu or full). The shipped Compose file maps .env's TIER=basic to it; GPU/Full tier files request their own tier. It ranks with the environment: a tier in config.yaml or Settings is ignored with a warning naming the variable, and Settings shows the tier as set by the environment. IMMICH_MEMORIES_TIER is only the plain environment form of the tier key, for an install that is not a deployment (a pip or uv install, say); do not set both. The tier guide explains what is detected.

Immich connection​

IMMICH_MEMORIES_IMMICH__API_VERSION="auto"

auto detects v2 or v3 at runtime; set v2/v3 only to diagnose a proxy that breaks detection. Check the connection with config test.

IMMICH_MEMORIES_ALLOW_LINK_LOCAL_URLS=true permits literal link-local addresses for configured service URLs. It is off by default and only read from the process environment, never Settings. See configured service addresses.

The ones that do not follow the pattern​

Session/encryption keys, logging and local ACE-Step process settings have their own names. See Environment variable exceptions. Scheduled jobs do not inherit your shell's exports; keep the Immich connection in YAML.

Native person identities​

IMMICH_MEMORIES_IMMICH__NATIVE_SHARING=true enables the optional native identity path. It defaults to false. Keep each selected owner's key configured: sharing does not expose the owner's favourites.