Environment variable exceptions
The variables that don't follow the IMMICH_MEMORIES_<SECTION>__<KEY> pattern: credential
shorthands, logging, local music and scheduling. Start with the
common variables.
The ones that do not follow the pattern
The captioner has its own credential. OPENAI_API_KEY does not reach it: give it
IMMICH_MEMORIES_EDITORIAL__PREPARATION__CAPTION_API_KEY, or leave it blank for a server that
needs none.
Shorthands
| Variable | Overrides |
|---|---|
IMMICH_URL | immich.url |
IMMICH_API_KEY | immich.api_key |
IMMICH_MEMORIES_DATABASE_URL | database.url, before the store opens |
IMMICH_MEMORIES_DATABASE_SCHEMA | database.schema, before the store opens |
IMMICH_MEMORIES_IMPORT_FROM | database.import_from, for the one-time legacy import |
OPENAI_API_KEY | llm.api_key, only when the config file states no key |
ANTHROPIC_API_KEY | llm.api_key under the same rule, read instead of OPENAI_API_KEY when llm.provider is anthropic or zai |
MUSICGEN_ENABLED, MUSICGEN_BASE_URL, MUSICGEN_API_KEY | musicgen.enabled, .base_url, .api_key |
ACE_STEP_ENABLED, ACE_STEP_API_URL, ACE_STEP_API_KEY | ace_step.enabled, .api_url, .api_key |
ACE_STEP_MODE | ace_step.mode (api or lib; other values ignored) |
IMMICH_MEMORIES_AUTH_USERNAME + IMMICH_MEMORIES_AUTH_PASSWORD | auth.username and auth.password, and sets auth.enabled=true, auth.provider=basic. Both must be set |
An empty shorthand counts as unset.
OPENAI_API_KEY is the name every OpenAI-SDK client reads, a local mlx or vLLM server included, so
on a machine that exports it for that server it says nothing about the endpoint the key will be
sent to. So a key in llm.api_key wins, and the variable fills the field only where the
file leaves it empty or holds a ${VAR} nobody set. ANTHROPIC_API_KEY works the same way. To
replace a key that is in the file, use IMMICH_MEMORIES_LLM__API_KEY.
--config PATH makes PATH the single config file, and the same variables apply to it.
Not config keys
| Variable | Effect |
|---|---|
IMMICH_MEMORIES_STORAGE_SECRET | Secret for the web UI session store. Priority: this variable, then the existing ~/.immich-memories/.storage_secret file. If neither exists, the web UI generates and saves that file once; later starts reuse it. 32+ random characters (openssl rand -hex 32); a shorter one, or one with a placeholder word like change-me, stops the app at startup |
IMMICH_MEMORIES_SKIP_STORED_SETTINGS | 1 starts without the settings saved in the database (env, config.yaml and defaults only). Without it, a store that is configured but unreadable stops the app (where a setting comes from) |
IMMICH_MEMORIES_SECRET_KEY | Encrypts the secrets saved to the database from the UI or CLI (API keys, passwords). Any string of 32+ characters, e.g. openssl rand -base64 32. Unset: secrets cannot be saved there, only in env or config.yaml. Read from the environment only, never from the store (secrets in the database) |
IMMICH_MEMORIES_LOG_FORMAT | text (default) or json |
IMMICH_MEMORIES_LOG_LEVEL | INFO (default), DEBUG, WARNING or ERROR. The CLI's -v and --log-level win for one run |
IMMICH_MEMORIES_LOG_FILE | Also write logs to this file |
IMMICH_FORCE_CPU | 1, true or yes puts the GPU kernels (titles and photo moves) on the CPU even with a GPU. FFmpeg's decode and encode are untouched |
IMMICH_MEMORIES_FONTS_DIR | Where titles fonts --install puts the Noto fonts for other alphabets and where titles look for them (default ~/.immich-memories/fonts/noto; the image sets its own) |
IMMICH_MEMORIES_MUSIC_DIR | Where models fetch unpacks the bundled music-v3 library and where films look for it (default ~/.immich-memories/models/music-v3; the image sets its own) |
IMMICH_MEMORIES_OWNER | Who "you" is in the people registry, for people scan (same as --owner) |
ACESTEP_CHECKPOINTS_DIR | ACE-Step lib mode: where checkpoints go (default ~/.cache/ace-step/checkpoints) |
ACESTEP_MLX_VAE_CHUNK | ACE-Step lib mode on Apple Silicon: VAE decode chunk in latent frames (minimum 192). Lower it if MLX runs out of memory |
IMMICH_MEMORIES_ACESTEP_MLX_DIT_FP32 | ACE-Step lib mode on Apple Silicon: 1 keeps the decoder in fp32 (about twice the memory) |
FORWARDED_ALLOW_IPS | uvicorn: proxies whose X-Forwarded-* headers are trusted. Wins over auth.trusted_proxies. With auth on, * stops the app at startup (list your proxy's address); with auth.provider: header remove the variable entirely, even if empty, and use auth.trusted_proxies. See Authentication |
A launchd or cron job starts from a login-less environment, so nothing you export interactively
reaches it. auto install copies PATH, ACESTEP_CHECKPOINTS_DIR, ACESTEP_MLX_VAE_CHUNK,
IMMICH_MEMORIES_ACESTEP_MLX_DIT_FP32 and PYTORCH_MPS_HIGH_WATERMARK_RATIO into the plist or
unit, and nothing else, since IMMICH_MEMORIES_* also holds credentials. Change one of them and
run auto install again.