Environment Variables¶

This document provides a complete reference of all environment variables supported by Immich Stack.

Required Variables¶

Variable	Description	Example
`API_KEY`	Immich API key(s)	`API_KEY=key1,key2`
`API_URL`	Immich API base URL	`API_URL=http://immich:2283/api`

Run Mode Configuration¶

Variable	Description	Default	Example
`RUN_MODE`	Run mode: "once" or "cron"	"once"	`cron`
`CRON_INTERVAL`	Interval in seconds for cron	60	`3600`

Stack Management¶

Variable	Description	Default	Example
`RESET_STACKS`	Delete all existing stacks before processing	false	`true`
`CONFIRM_RESET_STACK`	Confirmation message for reset	-	`"I acknowledge..."`
`REPLACE_STACKS`	Replace stacks for new groups	false	`true`
`DRY_RUN`	Simulate actions without making changes	false	`true`
`REMOVE_SINGLE_ASSET_STACKS`	Remove stacks containing only one asset	false	`true`

Parent Selection¶

Variable	Description	Default	Example
`PARENT_FILENAME_PROMOTE`	Substrings to promote as parent filenames. Supports empty string for negative matching, the `sequence` keyword and automatic sequence detection for burst photos.	-	`,_edited` or `edit,raw` or `COVER,sequence` or `0000,0001,0002,0003`
`PARENT_EXT_PROMOTE`	Extensions to promote as parent files	-	`.jpg,.dng`

Empty String for Negative Matching¶

An empty string ("") in the promote list acts as a negative match - it matches files that don't contain any of the other non-empty substrings in the list:

Example	Description	Effect
`,_edited`	Prioritize unedited files	Files without "_edited" are promoted first
`,_edited,_crop`	Prioritize clean filenames	Files without "_edited" or "_crop" come first
`COVER,,_edited`	Complex priority	COVER files first, then files without "_edited", then "_edited" files

Examples:

# Promote unedited JPGs over edited ones
PARENT_FILENAME_PROMOTE=,_edited
# Result: IMG_1234.jpg > IMG_1234_edited.jpg

# Multiple exclusions
PARENT_FILENAME_PROMOTE=,_edited,_crop,_cropped
# Result: IMG_1234.jpg > IMG_1234_edited.jpg > IMG_1234_crop.jpg > IMG_1234_cropped.jpg

Sequence Keyword¶

The sequence keyword provides flexible handling of sequential files (like burst photos):

Syntax	Description	Example Files	Result
`sequence`	Matches any numeric sequence	`IMG_0001.jpg`, `IMG_0010.jpg`, `IMG_0100.jpg`	Orders by numeric value: 1, 10, 100
`sequence:4`	Matches exactly 4-digit sequences	`IMG_0001.jpg`, `IMG_0010.jpg`	Only matches 4-digit numbers
`sequence:IMG_`	Matches sequences with specific prefix	`IMG_001.jpg`, `PHOTO_001.jpg`	Only orders files starting with `IMG_`

Mixed Promote Lists:

# Prioritize COVER files, then order remaining by sequence
PARENT_FILENAME_PROMOTE=COVER,sequence

# Prioritize edited files, then 4-digit sequences
PARENT_FILENAME_PROMOTE=edit,sequence:4

Automatic Sequence Detection (Legacy)¶

When PARENT_FILENAME_PROMOTE contains a numeric sequence pattern (e.g., 0000,0001,0002,0003), the system automatically:

Detects the sequence pattern (prefix, number, suffix)
Matches files that follow the same pattern
Orders files by their numeric value, even beyond the listed values
Works with various formats: IMG_0001, photo001, 1a, etc.

Note: The sequence keyword is recommended over listing individual numbers for better flexibility.

Asset Inclusion¶

Variable	Description	Default	Example
`WITH_ARCHIVED`	Include archived assets in processing	false	`true`
`WITH_DELETED`	Include deleted assets in processing	false	`true`

Custom Criteria¶

Variable	Description	Default	Example
`CRITERIA`	Custom grouping criteria JSON	-	See Custom Criteria

Logging¶

Variable	Description	Default	Example
`LOG_LEVEL`	Log level (debug,info,warn,error)	info	`debug`
`LOG_FORMAT`	Log format (json,text)	text	`json`

Examples¶

Basic Configuration¶

API_KEY=your_key
API_URL=http://immich:2283/api

Cron Mode¶

RUN_MODE=cron
CRON_INTERVAL=3600

Stack Management¶

RESET_STACKS=true
CONFIRM_RESET_STACK="I acknowledge all my current stacks will be deleted and new one will be created"
REPLACE_STACKS=true
DRY_RUN=false
REMOVE_SINGLE_ASSET_STACKS=true

Parent Selection¶

PARENT_FILENAME_PROMOTE=edit,raw
PARENT_EXT_PROMOTE=.jpg,.dng

Custom Criteria¶

CRITERIA='[{"key":"originalFileName","split":{"delimiters":["~","."],"index":0}},{"key":"localDateTime","delta":{"milliseconds":1000}}]'

Best Practices¶

Security
Never commit API keys to version control
Use environment-specific .env files
Rotate API keys regularly
Configuration
Use specific versions in production
Document all custom configurations
Test changes in development first
Monitoring
Enable debug logging when needed
Monitor cron job execution
Check stack operation results
Maintenance
Review and update configurations regularly
Clean up old stacks periodically
Monitor API usage and limits