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
| Variable | Purpose |
|---|---|
IMMICH_URL, IMMICH_API_KEY | Required Immich connection |
IMMICH_MEMORIES_IMMICH__PUBLIC_URL | Optional: 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_LONGITUDE | Home coordinates for trips and public holidays |
TZ | Daily timer and log timezone |
IMMICH_MEMORIES_AUTH_USERNAME, IMMICH_MEMORIES_AUTH_PASSWORD | Set 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_SECRET | Optional session signing key, generated when unset; 32+ random characters (openssl rand -hex 32) or the app refuses to start |
IMMICH_MEMORIES_SECRET_KEY | Encrypt credentials saved in Settings; shipped .env support |
IMMICH_MEMORIES_UPLOAD__ENABLED, IMMICH_MEMORIES_UPLOAD__ALBUM_NAME | Upload CLI/daily films; add to environment: |
IMMICH_MEMORIES_DEPLOYMENT_TIER | The deployment's tier: auto, basic, gpu or full (Compose .env: TIER) |
IMMICH_MEMORIES_DATABASE_URL | Optional 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.
Link-local services
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.