This is a python script designed to automatically create albums in Immich from a folder structure mounted into the Immich container. This is useful for automatically creating and populating albums for external libraries. Using the provided docker image, the script can simply be added to the Immich compose stack and run along the rest of Immich's containers.
Current compatibility: Immich v1.105.x and below
This script is mostly based on the following original script: REDVM/immich_auto_album.py
- Download the script and its requirements
curl https://raw.githubusercontent.com/Salvoxia/immich-folder-album-creator/main/immich_auto_album.py -o immich_auto_album.py
curl https://raw.githubusercontent.com/Salvoxia/immich-folder-album-creator/main/requirements.txt -o requirements.txt- Install requirements
pip3 install -r requirements.txt- Run the script
python3 ./immich_auto_album.py -h
usage: immich_auto_album.py [-h] [-r ROOT_PATH] [-u] [-a ALBUM_LEVELS] [-s ALBUM_SEPARATOR] [-c CHUNK_SIZE] [-C FETCH_CHUNK_SIZE] [-l {CRITICAL,ERROR,WARNING,INFO,DEBUG}] root_path api_url api_key
Create Immich Albums from an external library path based on the top level folders
positional arguments:
root_path The external libarary's root path in Immich
api_url The root API URL of immich, e.g. https://immich.mydomain.com/api/
api_key The Immich API Key to use
options:
-h, --help show this help message and exit
-r ROOT_PATH, --root-path ROOT_PATH
Additional external libarary root path in Immich; May be specified multiple times for multiple import paths or external libraries. (default: None)
-u, --unattended Do not ask for user confirmation after identifying albums. Set this flag to run script as a cronjob. (default: False)
-a ALBUM_LEVELS, --album-levels ALBUM_LEVELS
Number of sub-folders or range of sub-folder levels below the root path used for album name creation. Positive numbers start from top of the folder structure, negative numbers from the bottom. Cannot be 0. If a range should be set, the start level and end level must be separated by a comma
like '<startLevel>,<endLevel>'. If negative levels are used in a range, <startLevel> must be less than or equal to <endLevel>. (default: 1)
-s ALBUM_SEPARATOR, --album-separator ALBUM_SEPARATOR
Separator string to use for compound album names created from nested folders. Only effective if -a is set to a value > 1 (default: )
-c CHUNK_SIZE, --chunk-size CHUNK_SIZE
Maximum number of assets to add to an album with a single API call (default: 2000)
-C FETCH_CHUNK_SIZE, --fetch-chunk-size FETCH_CHUNK_SIZE
Maximum number of assets to fetch with a single API call (default: 5000)
-l {CRITICAL,ERROR,WARNING,INFO,DEBUG}, --log-level {CRITICAL,ERROR,WARNING,INFO,DEBUG}
Log level to use (default: INFO)
A Docker image is provided to be used as a runtime environment. It can be used to either run the script manually, or via cronjob by providing a crontab expression to the container. The container can then be added to the Immich compose stack directly.
The environment variables are analoguous to the script's command line arguments.
| Environment varible | Mandatory? | Description |
|---|---|---|
| ROOT_PATH | yes | A single or a comma separated list of import paths for external libraries in Immich |
| API_URL | yes | The root API URL of immich, e.g. https://immich.mydomain.com/api/ |
| API_KEY | yes | The Immich API Key to use |
| ALBUM_LEVELS | no | Number of sub-folders or range of sub-folder levels below the root path used for album name creation. Positive numbers start from top of the folder structure, negative numbers from the bottom. Cannot be 0. If a range should be set, the start level and end level must be separated by a comma. Refer to How it works for a detailed explanation |
| ALBUM_SEPARATOR | no | Separator string to use for compound album names created from nested folders. Only effective if -a is set to a value > 1 (default: " ") |
| CHUNK_SIZE | no | Maximum number of assets to add to an album with a single API call (default: 2000) |
| FETCH_CHUNK_SIZE | no | Maximum number of assets to fetch with a single API call (default: 5000) |
| LOG_LEVEL | no | Log level to use (default: INFO), allowed values: CRITICAL,ERROR,WARNING,INFO,DEBUG |
To perform a manually triggered run, use the following command:
docker run -e API_URL="https://immich.mydomain.com/api/" -e API_KEY="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" -e ROOT_PATH="/external_libs/photos" salvoxia/immich-folder-album-creator:latest /script/immich_auto_album.shTo set up the container to periodically run the script, give it a name, pass the TZ variable and a valid crontab expression as environment variable. This example runs the script every hour:
docker run --name immich-folder-album-creator -e TZ="Europe/Berlin" -e CRON_EXPRESSION="0 * * * *" -e API_URL="https://immich.mydomain.com/api/" -e API_KEY="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" -e ROOT_PATH="/external_libs/photos" salvoxia/immich-folder-album-creator:latestIf your external library uses multiple import paths or you have set up multiple external libraries, you can pass multiple paths in ROOT_PATH by setting it to a comma separated list of paths:
docker run --name immich-folder-album-creator -e TZ="Europe/Berlin" -e CRON_EXPRESSION="0 * * * *" -e API_URL="https://immich.mydomain.com/api/" -e API_KEY="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" -e ROOT_PATH="/external_libs/photos,/external_libs/more_photos" salvoxia/immich-folder-album-creator:latestAdding the container to Immich's docker-compose.yml file:
version: "3.8"
#
# WARNING: Make sure to use the docker-compose.yml of the current release:
#
# https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml
#
# The compose file on main may not be compatible with the latest release.
#
name: immich
services:
immich-server:
container_name: immich_server
volumes:
- /path/to/my/photos:/external_libs/photos
...
immich-folder-album-creator:
container_name: immich_folder_album_creator
image: salvoxia/immich-folder-album-creator:latest
restart: unless-stopped
environment:
API_URL: http://immich_server:3001/api
API_KEY: xxxxxxxxxxxxxxxxx
ROOT_PATH: /external_libs/photos
CRON_EXPRESSION: "0 * * * *"
TZ: Europe/Berlin
The script utilizies Immich's REST API to query all images indexed by Immich, extract the folder for all images that are in the top level of any provided root_path, then creates albums with the names of these folders (if not yet exists) and adds the images to the correct albums.
The following arguments influence what albums are created:
root_path, --album-levels and --album-separator
root_pathis the base path where images are looked for. Multiple root paths can be specified by adding the-rargument as many times as necessary. Only images within that base path will be considered for album creation.--album-levelscontrols how many levels of nested folders are considered when creating albums. The default is1. For examples see below.--album-separatorsets the separator used for concatenating nested folder names to create an album name. It is a blank by default.
Examples:
Suppose you provide an external library to Immich under the path /external_libs/photos.
The folder structure of photos might look like this:
/external_libs/photos/2020
/external_libs/photos/2020/02 Feb
/external_libs/photos/2020/02 Feb/Vacation
/external_libs/photos/2020/08 Aug/Vacation
/external_libs/photos/Birthdays/John
/external_libs/photos/Birthdays/Jane
/external_libs/photos/Skiing 2023
Albums created for root_path = /external_libs/photos (--album-levels is implicitly set to 1):
2020(containing all images from2020and all sub-folders)Birthdays(containing all images from Birthdays itself as well asJohnandJane)Skiing 2023
Albums created for root_path = /external_libs/photos/Birthdays:
JohnJane
Albums created for root_path = /external_libs/photos and --album-levels = 2:
2020(containing all images from2020itself, if any)2020 02 Feb(containing all images from2020/02 Febitself,2020/02 Feb/Vacationand2020/02 Aug/Vacation)Birthdays John(containing all imags fromBirthdays/John)Birthdays Jane(containing all imags fromBirthdays/John)Skiing 2023
Albums created for root_path = /external_libs/photos, --album-levels = 3 and --album-separator " - " :
2020(containing all images from2020itself, if any)2020 - 02 Feb(containing all images from02 Febitself, if any)2020 - 02 Feb - Vacation(containing all imags from2020/02 Feb/Vacation)2020 - 08 Aug - Vacation(containing all imags from2020/02 Aug/Vacation)Birthdays - JohnBirthdays - JaneSkiing 2023
Albums created for root_path = /external_libs/photos, --album-levels = -1 and --album-separator " - " :
2020(containing all images from2020itself, if any)02 Feb(containing all images from2020/02 Febitself, if any)Vacation(containing all images from2020/02 Feb/VacationAND2020/08 Aug/Vacation)John(containing all imags fromBirthdays/John)Jane(containing all imags fromBirthdays/Jane)Skiing 2023
It is possible to specify not just a nunmber for album-levels, but a range from level x to level y in the folder structure that should make up an album's name:
--album-levels="2,3"
The range is applied to the folder structure beneath root_path from the top for positive levels and from the bottom for negative levels.
Suppose the following folder structure for an external library with the script's root_path set to /external_libs/photos:
/external_libs/photos/2020/2020 02 Feb/Vacation
/external_libs/photos/2020/2020 08 Aug/Vacation
--album-levels="2,3"will create albums (for this folder structure, this is equal to--album-levels="-2")2020 02 Feb Facation2020 08 Aug Vacation
--album-levels="2,2"will create albums (for this folder structure, this is equal to--album-levels="-2,-2")2020 02 Feb2020 08 Aug
album-levels or album level ranges, images from different parent folders will be mixed in the same album if they reside in sub-folders with the same name (see Vacation in example above).
Since Immich does not support real nested albums (yet?), neither does this script.
