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

> Organize iCloud photos by year month and day using docker-icloudpd. Set the folder structure to YYYY/MM/DD in your icloudpd.conf file for automatic organization.

- Repository: [boredazfcuk/docker-icloudpd](https://github.com/boredazfcuk/docker-icloudpd)
- Tags: how-to-guide
- Published: 2026-02-26

---

**Set `folder_structure={:%Y/%m/%d}` in [`/config/icloudpd.conf`](https://github.com/boredazfcuk/docker-icloudpd/blob/main//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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main//config/icloudpd.conf). Edit this file to set your preferred folder structure:

```bash

# 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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/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:

```bash
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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/sync-icloud.sh):

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

```

As shown in [`sync-icloud.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/sync-icloud.sh) executes (line 85), it constructs the command line for the `icloudpd` binary:

```bash
/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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main//config/icloudpd.conf).
- The setting is passed to the `icloudpd` binary via [`sync-icloud.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/init_config.sh) and written to [`/config/icloudpd.conf`](https://github.com/boredazfcuk/docker-icloudpd/blob/main//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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main//config/icloudpd.conf) and set `folder_structure={:%Y/%B}` to apply your custom organization scheme.