# Environment variables

Markdown version of <https://sam-dumont.github.io/immich-memories/docs/run/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.

```ini
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`:

```yaml
      IMMICH_MEMORIES_TRIPS__HOMEBASE_LATITUDE: "50.8503"
      IMMICH_MEMORIES_TRIPS__HOMEBASE_LONGITUDE: "4.3517"
```

After an edit:

```bash
docker compose up -d
```

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

```yaml
      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](https://sam-dumont.github.io/immich-memories/docs/better/reader.md), [caption](https://sam-dumont.github.io/immich-memories/docs/better/captions.md),
[inference](https://sam-dumont.github.io/immich-memories/docs/better/inference.md), [render](https://sam-dumont.github.io/immich-memories/docs/better/gpu-render.md) or [music](https://sam-dumont.github.io/immich-memories/docs/better/music.md)
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:`.

```ini
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:

```ini
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](https://sam-dumont.github.io/immich-memories/docs/reference/config-reference.md).

## 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](https://sam-dumont.github.io/immich-memories/docs/run/authentication.md#the-generated-password)). `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](https://sam-dumont.github.io/immich-memories/docs/run/reference/environment.md) 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](https://sam-dumont.github.io/immich-memories/docs/run/config-file.md#secrets-in-the-database).
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](https://sam-dumont.github.io/immich-memories/docs/run/config-file.md#where-a-setting-comes-from).
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](https://sam-dumont.github.io/immich-memories/docs/run/requirements.md#which-tier-you-get) explains what is detected.

### Immich connection

```ini
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](https://sam-dumont.github.io/immich-memories/docs/run/config-file.md#immich-api-compatibility) 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](https://sam-dumont.github.io/immich-memories/docs/run/network-security.md#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](https://sam-dumont.github.io/immich-memories/docs/run/reference/environment.md).
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](https://sam-dumont.github.io/immich-memories/docs/run/multi-account.md#native-person-identities). It defaults to `false`.
Keep each selected owner's key configured: sharing does not expose the owner's favourites.
