Folder Structure

Folder Structure

icloudpd-rs organizes downloaded photos into date-based subdirectories within your download directory.

Default Layout

With the default --folder-structure "%Y/%m/%d", a photo taken on March 15, 2024 is saved to:

/photos/2024/03/15/IMG_1234.HEIC

Custom Templates

The folder structure is a strftime format string applied to each asset's creation date:

Template	Example path
%Y/%m/%d	2024/03/15/IMG_1234.HEIC
%Y/%m	2024/03/IMG_1234.HEIC
%Y	2024/IMG_1234.HEIC
none	IMG_1234.HEIC

The Python {:%Y/%m/%d} syntax is also accepted for compatibility with existing configurations.

Filename Handling

Within each folder, filenames are preserved from iCloud. Characters that are invalid on the local filesystem (/\:*?"<>|) are stripped.

Album Name Sanitization

When downloading from specific albums, album names are used as directory components. These are sanitized to prevent path traversal attacks or invalid directories:

• Directory traversal sequences (..) are replaced with _
• Leading/trailing dots and spaces are stripped
• Windows reserved names (CON, NUL, PRN, COM1–COM9, LPT1–LPT9) are prefixed with _
• Invalid filesystem characters are removed

Compatibility with Python Version

The Rust version produces identical folder paths when using the same template string. If you're migrating from the Python version with the default folder structure, your existing directory layout will be preserved.

Related Flags

• --folder-structure
• --directory