Folder Structure

Folder Structure

kei uses one directory template per pass: album, smart folder, and unfiled.

Config

[download]
directory = "/photos"
folder_structure = "%Y/%m/%d"
folder_structure_albums = "{album}"
folder_structure_smart_folders = "{smart-folder}"

Pass	Key	Default	Token
Album	folder_structure_albums	{album}	{album}
Smart folder	folder_structure_smart_folders	{smart-folder}	{smart-folder}
Unfiled	folder_structure	%Y/%m/%d	none

All three templates accept {library} as the first segment. Standard strftime specifiers such as %Y, %m, and %d are supported. The Python {:%Y/%m/%d} shape is also accepted.

Defaults

With the default templates:

Asset type	Path
Photo in user album Vacation 2024	/photos/Vacation 2024/IMG_1234.HEIC
Photo in smart folder Favorites	/photos/Favorites/IMG_1234.HEIC
Photo in no user album	/photos/2024/03/15/IMG_1234.HEIC

Smart-folder passes are off by default. Enable them in [filters].smart_folders.

Pass behavior

[filters]
albums = ["all"]
smart_folders = ["none"]
unfiled = true

A photo in N albums writes N on-disk copies when the album template produces distinct paths per {album}. The unfiled pass excludes assets that are in any user album, so albumed assets don't also appear in the unfiled tree.

Examples

Date hierarchy under each album:

[download]
folder_structure_albums = "{album}/%Y/%m/%d"

Only specific albums, no unfiled pass:

[filters]
albums = ["Vacation", "Family"]
unfiled = false

Smart folders with dates:

[filters]
smart_folders = ["all"]

[download]
folder_structure_smart_folders = "{smart-folder}/%Y/%m/%d"

Multi-library

When more than one library is in scope, prefix active templates with {library} to keep paths separate:

[filters]
libraries = ["all"]

[download]
folder_structure = "{library}/%Y/%m/%d"
folder_structure_albums = "{library}/{album}"

{library} renders as PrimarySync for the personal library or a truncated shared-library zone name such as SharedSync-A1B2C3D4.

Token placement rules

• {library} must be the first path segment when present.
• {album} in folder_structure_albums must come before any strftime specifier and after {library} if present.
• {smart-folder} follows the same rule in folder_structure_smart_folders.
• Each token may appear at most once per template.

Examples:

Template	Valid?
{album}	yes
{album}/%Y/%m/%d	yes
{library}/{album}/%Y	yes
Photos/{album}/%Y	no
%Y/{album}/%m	no
{album}/%Y/{album}	no

Name sanitization

Names used as directory components are sanitized to prevent path traversal and invalid directories:

• .. becomes _
• Leading/trailing dots and spaces are stripped
• Windows reserved names are prefixed with _
• Invalid filesystem characters are removed

Related

• Configuration
• Content Filtering
• Migration from Python