How to Configure Folder Structure for Photo Downloads in docker-icloudpd (YYYY/MM/DD)

Set folder_structure={:%Y/%m/%d} in /config/icloudpd.conf to organize iCloud photos into year/month/day directories.

The boredazfcuk/docker-icloudpd container downloads iCloud photos and videos to your local storage using a configurable folder hierarchy. By default, it organizes files into a YYYY/MM/DD structure, but you can customize this pattern or disable sub-folders entirely using the folder_structure configuration option.

Understanding the folder_structure Configuration Option

The folder_structure setting accepts a strftime-style template that determines how downloaded files are grouped into sub-directories within your download_path. This template uses Python datetime format codes wrapped in curly braces.

Default Behavior and strftime Templates

According to init_config.sh at line 102, the default value is {:%Y/%m/%d}. This creates a nested directory tree where:

• %Y creates a four-digit year folder (e.g., 2024)
• %m creates a two-digit month folder (e.g., 03)
• %d creates a two-digit day folder (e.g., 27)

The resulting path looks like: /home/user/iCloud/2024/03/27/IMG_1234.HEIC.

Three Ways to Configure Photo Download Folders

You can set the folder_structure option through three different methods, though the configuration file approach is recommended for persistent settings.

Method 1: Configuration File (Recommended)

When the container first starts, it generates /config/icloudpd.conf. Edit this file to set your preferred folder structure:

# Inside the container or on the host volume mounted at /config

vi /config/icloudpd.conf

# Add or modify this line:

folder_structure={:%Y/%m/%d}

This method persists across container restarts and is documented in CONFIGURATION.md at line 36.

Method 2: Environment Variable (Deprecated)

You can pass the setting as an environment variable when creating the container, though this method will be removed in future releases:

docker create \
  --name icloudpd \
  --volume icloudpd_config:/config \
  --volume /home/user/iCloud:/home/user/iCloud \
  --env folder_structure='{:%Y/%m/%d}' \
  boredazfcuk/icloudpd

Method 3: Command-Line Override

For one-time executions or testing, override the setting via the wrapper script sync-icloud.sh:

docker exec -it icloudpd \
  /usr/local/bin/sync-icloud.sh --folder-structure '{:%Y/%m/%d}'

As shown in sync-icloud.sh at line 2225, this forwards the value directly to the underlying icloudpd binary.

How Folder Structure Works Under the Hood

When sync-icloud.sh executes (line 85), it constructs the command line for the icloudpd binary:

/opt/icloudpd/bin/icloudpd --directory ${download_path} \
    --folder-structure ${folder_structure} …

The icloudpd binary interprets the strftime pattern using each photo's creation date metadata, then creates the appropriate sub-folders before writing the file. This ensures photos are organized chronologically based on when they were captured, not when they were downloaded.

Important Limitations and Considerations

Changing the folder_structure setting does not reorganize files that have already been downloaded. The setting only affects new downloads going forward. If you need to reorganize existing photos, you must manually move files or re-download them after clearing the library.

Additionally, setting folder_structure=none disables all sub-folder creation, placing all files directly in the download_path. According to launcher.sh at line 443, this disables certain dependent features such as delete_accompanying and delete_empty_directories, as these require a directory tree to function properly.

Summary

• The folder_structure configuration option controls how iCloud photos are organized into sub-directories using strftime templates.
• The default value {:%Y/%m/%d} creates a YYYY/MM/DD hierarchy, configurable via /config/icloudpd.conf.
• The setting is passed to the icloudpd binary via sync-icloud.sh and only affects new downloads, not existing files.
• Setting folder_structure=none disables sub-folders but also disables features that depend on directory traversal.

Frequently Asked Questions

What is the default folder structure for photo downloads?

The default folder structure is {:%Y/%m/%d}, which organizes photos into a nested hierarchy of year, month, and day folders (e.g., 2024/03/27/). This default is defined in init_config.sh and written to /config/icloudpd.conf during initial container setup.

Can I change the folder structure after photos have already been downloaded?

No, changing the folder_structure setting only affects new downloads. Existing photos remain in their current locations. To reorganize previously downloaded content, you must manually move files to match the new structure or delete and re-download your iCloud library after changing the configuration.

What happens if I set folder_structure to none?

Setting folder_structure=none places all downloaded files directly into the root download_path without any sub-folders. However, this disables certain features that require directory traversal, including delete_accompanying and delete_empty_directories, as noted in launcher.sh at line 443.

How do I create a custom date-based folder structure?

Use Python strftime format codes within curly braces to define custom patterns. For example, use {:%Y/%B} for 2024/March (full month name) or {:%Y/%U} for year and week number. Edit /config/icloudpd.conf and set folder_structure={:%Y/%B} to apply your custom organization scheme.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}