# How the Synology Photos App Fix Triggers Indexing After Downloads in docker-icloudpd

> Learn how the Synology Photos app fix triggers indexing for HEIC files downloaded by docker-icloudpd. Discover how timestamp manipulation ensures photos appear automatically.

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

---

**The Synology Photos app fix manipulates file timestamps to force the Synology indexing daemon to recognize newly downloaded HEIC files, ensuring they appear in the Photos app without manual intervention.**

The **Synology Photos app fix** is a specialized feature in the [docker-icloudpd](https://github.com/boredazfcuk/docker-icloudpd) container that solves a specific integration problem: Synology’s Photos app does not automatically detect media files downloaded by external tools. By enabling the `synology_photos_app_fix` configuration option, users can automate the indexing trigger, ensuring every HEIC file downloaded from iCloud immediately appears in their Synology library.

## How the Synology Photos App Fix Works

When enabled, the fix executes a precise sequence of filesystem operations that generate the exact metadata change events the Synology Photos daemon monitors. This process runs automatically after each successful download batch completes.

### Configuration and Activation

The feature is controlled by the **`synology_photos_app_fix`** boolean flag, which defaults to `false` as defined in [`init_config.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/init_config.sh) at line 168. To activate the fix, set the environment variable or configuration file entry to `true`:

```bash

# In your docker-compose environment or icloudpd.conf

synology_photos_app_fix=true

```

Once enabled, the main synchronization script [`sync-icloud.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/sync-icloud.sh) invokes the fix function at lines 2326-2329 immediately after the download phase completes:

```bash
if [ "${synology_photos_app_fix}" = true ]; then
   synology_photos_app_fix
fi

```

### The Timestamp Manipulation Process

The `synology_photos_app_fix()` function, implemented at lines 1635-1650 in [`sync-icloud.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/sync-icloud.sh), performs a four-step timestamp dance for every newly downloaded HEIC file:

1. **Parse the sync log** – The function greps `/tmp/icloudpd/icloudpd_sync.log` for lines containing `"Downloaded /"` and ending with `".HEIC"`, extracting the absolute path of each new file.

2. **Create a temporary reference** – For each HEIC file, it creates an empty companion file with the extension `.TMP` and copies the original file’s timestamps to it using `touch --reference`. This preserves the original capture date metadata.

3. **Trigger the indexing event** – The script first runs `touch "${heic_file}"` to update the file’s access and modification timestamps to the current time, forcing the filesystem to emit a change event that the Synology Photos daemon detects. It then immediately restores the original timestamps by re-applying the reference from the `.TMP` file, ensuring the photo retains its correct chronological placement in the library.

4. **Clean-up** – Unless the user has set `persist_temp_files`, the temporary `.TMP` reference file is deleted.

## Implementation Details in sync-icloud.sh

The complete implementation relies on precise shell operations within the [`sync-icloud.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/sync-icloud.sh) script. Here is the core function that performs the timestamp manipulation:

```bash
synology_photos_app_fix()
{
   IFS=$'\n'
   log_info "Fixing Synology Photos App import issue..."
   for heic_file in $(grep "Downloaded /" /tmp/icloudpd/icloudpd_sync.log \
                      | grep -i ".HEIC" | cut --delimiter " " --fields 9-)
   do
      log_debug "Create empty date/time reference file ${heic_file%.*}.TMP"
      run_as "touch --reference=\"${heic_file}\" \"${heic_file%.*}.TMP\""
      log_debug "Set time stamp for ${heic_file} to current: $(date)"
      run_as "touch \"${heic_file}\""
      log_debug "Set time stamp for ${heic_file} to original: $(date -r "${heic_file%.*}.TMP" +"%a %b %e %T %Y")"
      run_as "touch --reference=\"${heic_file%.*}.TMP\" \"${heic_file}\""
      log_debug "Removing temporary file ${heic_file%.*}.TMP"
      if [ -z "${persist_temp_files}" ]; then rm "${heic_file%.*}.TMP"; fi
   done
   IFS="${OLDIFS}"
}

```

This function is invoked conditionally based on the configuration flag, ensuring the fix only runs when explicitly enabled by the user.

## Summary

The **Synology Photos app fix** in docker-icloudpd solves the integration gap between iCloud downloads and Synology’s media indexing daemon through precise filesystem timestamp manipulation:

- **Configuration**: Enable by setting `synology_photos_app_fix=true` in your container environment.
- **Trigger**: The fix runs automatically in [`sync-icloud.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/sync-icloud.sh) after each download batch completes.
- **Mechanism**: It creates temporary reference files, updates HEIC file timestamps to trigger indexing events, then restores original metadata to preserve chronological order.
- **Scope**: Currently targets HEIC files specifically by parsing the `icloudpd_sync.log` for downloaded images.

## Frequently Asked Questions

### What file types does the Synology Photos app fix support?

The current implementation specifically targets **HEIC files** (High Efficiency Image Container). The `synology_photos_app_fix()` function in [`sync-icloud.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/sync-icloud.sh) greps the sync log for entries ending in `.HEIC` (case-insensitive), meaning JPEG or other formats downloaded by icloudpd are not currently processed by this fix.

### Do I need to manually rescan my Synology Photos library after enabling this fix?

No manual rescan is required when the **Synology Photos app fix** is enabled. The timestamp manipulation sequence—specifically the `touch` command that updates the file’s modification time—generates the exact filesystem events that the Synology Photos indexing daemon monitors. This forces automatic detection and import of newly downloaded media without user intervention.

### Will enabling this fix preserve my photos' original capture dates?

Yes, the fix preserves original capture dates through a **reference file technique**. Before modifying timestamps, the script creates a temporary `.TMP` file with `touch --reference` to store the original metadata. After triggering the indexing event with a fresh timestamp, it immediately restores the original dates by re-applying the reference. This ensures photos appear in correct chronological order within the Synology Photos timeline.

### Can I keep the temporary .TMP files for debugging purposes?

Yes, you can prevent cleanup of temporary files by setting the **`persist_temp_files`** environment variable or configuration option. By default, the `synology_photos_app_fix()` function removes the `.TMP` reference files immediately after restoring timestamps. However, if `persist_temp_files` is set to any non-empty value, the conditional cleanup at the end of the function is skipped, leaving the temporary files in place for troubleshooting or verification.