# immich-folder-album-creator, albums built from a folder tree

> immich-folder-album-creator is a Python script that creates and populates albums in an Immich server from the folder structure of an external library, and it is distributed both as a plain script and as a container image that joins an existing Immich compose stack. The parts that need care are the Immich version pairing, the API key permissions, and the fact that the album tree is something the tool reconstructs rather than something it owns.

**Salvoxia/immich-folder-album-creator** — Automatically create and populate albums in Immich from a folder structure in external libraries

- Repository: https://github.com/Salvoxia/immich-folder-album-creator
- Website: https://hub.docker.com/r/salvoxia/immich-folder-album-creator
- Stars: 1,204 · Forks: 63
- Language: Python
- License: MIT
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/salvoxia-immich-folder-album-creator

## The filesystem is the source of truth

The script is described as a Python program designed to automatically create albums in Immich from a folder structure mounted into the Immich container, and the README says it is useful for automatically creating and populating albums for external libraries. That framing decides everything about how it behaves. Your folder names are the album names, your nesting is the album hierarchy, and the assets under a folder become the album contents. The alternative arrangement, where a person creates albums by hand in the Immich interface, does not scale to a library that is already organised, and this script exists to bridge the two views. The disclaimer section records that the script is originally based on an earlier script by REDVM, published as a gist, so the design lineage is short and the current implementation is a maintained evolution of that original rather than a new idea.

## The Immich version and the client version have to agree

The compatibility section is the part to read first. The script requires an Immich server of v3.0.0 or later, and every API call goes through the immichpy client, with the supported server versions listed in the immichpy COMPATIBILITY.csv file. For a bare script you update requirements.txt so the immichpy version matches your server version, and the checked in file pins immichpy==5.0.0 with a comment pointing at the compatibility table. For the container images the rule is different, since new images are released whenever there is a breaking API change and as soon as a new immichpy version covers those changes, so the latest image supports the latest server. The README also records the history, that previous versions of the script up to v0.25.3 support Immich server versions v1.106.1 to v2.7.x. The practical consequence is that a server upgrade is a script upgrade, and the pairing is something you have to check rather than assume.

## One API key per user, with a long permission list

An API key is required for each user the script is used for, and since Immich server v1.135.x the key can carry specific permissions. The README lists the permissions required for the script to work with any possible option, and the list is worth reading as a checklist. For assets there is asset.read, asset.delete and asset.update. For albums there is album.create, album.read, album.update and album.delete. For album assets there is albumAsset.create, for album users there is albumUser.create, albumUser.update and albumUser.delete, and for the user itself user.read. The list is valid for Immich v3.0.0, which matters because the album delete permission in particular is the one that lets the cleanup modes do their work, and the album user permissions are what make automatic sharing possible.

## Running it as a plain script

The bare script route is three steps, and the first one is a curl that writes the script and its requirements into the working directory.

```bash
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
```

The requirements are then installed, with the note to make sure the immichpy version in that file matches your server version.

```bash
pip3 install -r requirements.txt
```

The script itself has a wide option set, and the usage line in the README is the reference. The positional arguments are root_path, api_url and api_key, and the flags cover the source of the tree, literal or file, the root path, the album levels to create, the album name separator, a pattern and replacement pair, chunk sizes, log level, ignore lists and an ignore regex, the mode with CREATE, CLEANUP and DELETE_ALL, sharing with a role of EDITOR or VIEWER, sorting, path filters with a regex variant, thumbnail selection from first, last, random, random-all or random-filtered, asset visibility of archive, locked or timeline, reading album properties, an API timeout, comments and likes toggles, a property update mode, a retry count and a thread count from one to twenty. That is a lot of surface, and the album level and separator options are the two that decide the shape of the tree.

## The container image runs a cron inside your Immich stack

The Docker image is the route most people will take, and the Dockerfile is more interesting than a simple copy. It starts from python:3.14-alpine3.22 and installs supercronic, the cron implementation that does not need a running cron daemon, with a pinned release URL for version 0.2.43 and a per platform SHA1 checksum for linux/amd64, linux/arm64 and linux/arm/v7. The crontab directory is set to /script/cron and an IS_DOCKER flag is exported. The build also installs the Python requirements, and the comment explains that gcc and musl-dev are needed to build the regex Python module on the arm/v7 platform, which are then removed again. The container runs as the non-root user 1000 and uses tini as the entry point wrapper around the setup_cron.sh script, so the cron schedule is initialised at container start rather than baked in.

## Sharing, filtering, cleanup and the album properties file

The table of contents shows how much sits behind the simple idea of creating albums. There is automatic album sharing, with the share target and the role of editor or viewer, and the README gives separate examples for the bare script and for Docker, which suggests the two paths differ in how the parameters are passed. There is a filtering layer with two directions, ignoring assets by name or pattern, and filtering for assets by path with a path filter and a path filter regex, with worked examples. There is album naming by regular expression, again with examples. There are cleanup modes, CLEANUP and DELETE_ALL, and the section on assets in multiple albums addresses the case where one file belongs to more than one folder. Album thumbnails can be set from the first, last or a random file, and the .albumprops file format lets a folder carry fine properties such as a description, with a documented precedence between the file and other sources, an opt-in discovery flag, and a mass update command. The last entries in the table are about asset visibility and the locked folder setting, and about how the tool reacts when the external library on disk changes underneath it.

## The API key should be a secret, not an environment variable

The README gives two docker-compose examples for passing the API key, one with the key as an environment variable and one using a secrets file, and the pairing is the point. The environment variable form is the one that ends up in a compose file in a repository, and a key with album delete and album user permissions is not something to commit. The secrets file form is the one to prefer for that reason. The repository layout is small and consistent with a single script project, with the script immich_auto_album.py, the requirements file, a docker/ directory holding the shell scripts the image copies in, a .pylintrc, a Dockerfile and the GitHub workflows for CI and for building the image, and the image is published on Docker Hub as salvoxia/immich-folder-album-creator. The licence position needs checking before you redistribute anything, since the project licence is recorded as unknown and there is no licence file at the top level of the repository.

## Conclusion

immich-folder-album-creator fits a self hosted Immich user whose external library is already organised into folders and who wants that structure mirrored as albums instead of a flat pile of assets. It does not fit someone who wants Immich to derive albums from its own metadata, because the source of truth here is the filesystem, and it does not fit a deployment where the API key cannot carry the album and album user permissions the script needs. Verify three things before you run it: that your Immich server version has a matching immichpy version in the compatibility table, that the API key you create carries exactly the permissions listed in the README, and what the cleanup and delete modes do to albums that already exist, because the tool operates on a server that has your real library in it.

## FAQ

### What does immich-folder-album-creator do?

It is a Python script that automatically creates and populates albums in Immich from a folder structure mounted into the Immich container, which is useful for external libraries. It is based originally on an earlier script by REDVM and is distributed as a plain script and as a Docker image.

### Which Immich versions does immich-folder-album-creator support?

It requires an Immich server of v3.0.0 or later, and every API call goes through the immichpy client, with the mapping between server and client versions in the immichpy COMPATIBILITY.csv. Previous versions of the script up to v0.25.3 support server versions v1.106.1 to v2.7.x.

### What API key permissions does the script need?

One key per user, with permissions for asset.read, asset.delete and asset.update, album.create, album.read, album.update and album.delete, albumAsset.create, albumUser.create, albumUser.update, albumUser.delete, and user.read, and the list is stated as valid for Immich v3.0.0.

### How do I run immich-folder-album-creator with Docker?

The image is published as salvoxia/immich-folder-album-creator and can be added to the Immich compose stack. The image runs a supercronic based cron so the schedule is initialised at container start, and the README gives compose examples both with the API key as an environment variable and with a secrets file.

## Sources

- [Issues](https://github.com/Salvoxia/immich-folder-album-creator/issues)
- [Project website](https://hub.docker.com/r/salvoxia/immich-folder-album-creator)
- [README](https://github.com/Salvoxia/immich-folder-album-creator/blob/main/README.md)
- [Releases](https://github.com/Salvoxia/immich-folder-album-creator/releases)
- [Salvoxia/immich-folder-album-creator on GitHub](https://github.com/Salvoxia/immich-folder-album-creator)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/salvoxia-immich-folder-album-creator