Skip to content

Quick Start

Basic Usage

  1. Create a .env file:
cat > .env << EOL
API_KEY=your_immich_api_key
API_URL=http://immich-server:2283/api
RUN_MODE=cron
CRON_INTERVAL=60
EOL
  1. Run with Docker (using Docker Hub):
docker run -d --name immich-stack --env-file .env -v ./logs:/app/logs majorfi/immich-stack:latest

Or using GitHub Container Registry:

docker run -d --name immich-stack --env-file .env -v ./logs:/app/logs ghcr.io/majorfi/immich-stack:latest

Running Locally

  1. Create a .env file in your working directory with your Immich credentials:
API_KEY=your_immich_api_key
API_URL=http://your_immich_server:3001/api
  1. Run the stacker:
# Using the binary
./immich-stack

# Or if installed in PATH
immich-stack

Available Commands

Create Stacks (Default)

# Run the main stacking operation
immich-stack
# Or explicitly:
immich-stack stack

Find Duplicates

# Identify duplicate assets in your library
immich-stack duplicates

Fix Trash Consistency

# Move related assets to trash when their companions are trashed
immich-stack fix-trash --dry-run  # Preview first
immich-stack fix-trash             # Execute
  1. Optional: Configure additional options via environment variables or flags:
# Example with flags
./immich-stack --dry-run --parent-filename-promote=edit --parent-ext-promote=.jpg,.dng --with-archived --with-deleted

# Or using environment variables
export DRY_RUN=true
export PARENT_FILENAME_PROMOTE=edit
export PARENT_EXT_PROMOTE=.jpg,.dng
export WITH_ARCHIVED=true
export WITH_DELETED=true
./immich-stack

Burst Photo Example

For burst photos from cameras like Sony, Canon, etc., you can use the flexible sequence keyword or numeric sequences:

# Order any burst photos by their numeric sequence
export PARENT_FILENAME_PROMOTE=sequence

# For Sony burst photos with COVER priority
export PARENT_FILENAME_PROMOTE=COVER,sequence

# For Canon burst photos with specific 4-digit format
export PARENT_FILENAME_PROMOTE=sequence:4

# For files with specific prefix
export PARENT_FILENAME_PROMOTE=sequence:IMG_

./immich-stack

Using Numeric Sequences (Legacy)

# For Sony burst photos (DSCPDC_0000_BURST..., DSCPDC_0001_BURST..., etc.)
export PARENT_FILENAME_PROMOTE=0000,0001,0002,0003

# For Canon burst photos (IMG_0001, IMG_0002, etc.)
export PARENT_FILENAME_PROMOTE=IMG_0001,IMG_0002,IMG_0003

# The system automatically detects sequences and orders photos correctly
# Even files beyond your list (e.g., 0999) will be sorted properly
./immich-stack