File Naming

Assets on iCloud have names. When downloading assets, icloudpd can adjust names.

Folder Structure

Changed in version 1.7.0: Support for none value added

Changed in version 1.22.0: Support for OS locale added

icloudpd uses asset metadata (created date) to build folder hierarchy, and it can be adjusted with --folder-structure parameter.

Specifying --folder-structure none will put all files into one folder.

Formatting

icloudpd follows Python string formatting grammar for --folder-structure parameter,e.g. {:%Y} means the need to take only 4-digit year out of created date. Full list of format codes is available.

Default format is: {:%Y/%m/%d}

Language-specific formatting

Added in version 1.22.0.

Some formatting codes, e.g. %B for printing full month, are specific to the language. By default icloudpd uses English regardless of the locale of the OS. With --use-os-locale the behavior can be changed.

Example of running icloudpd with specific locale under Linux or MacOS:

LC_ALL=ru_RU.UTF.8 icloudpd --use-os-locale --version

Duplicates

Changed in version 1.20.0: --file-match-policy parameter added and name-id7 policy implemented

In large iCloud collections it is possible to have name collisions. To avoid collisions if files need to be downloaded into the same folder, use --file-match-policy parameter:

  • add unique invariant asset identification suffix to the name (e.g. “IMG_1234_QAZXSW.JPG”) with --file-match-policy name-id7

  • de-duplicate by adding file size as a suffix (e.g. “IMG_1234-67890.JPG” for second asset); --file-match-policy name-size-dedup-with-suffix - it is default

Live Photos

Changed in version 1.18.0: --live-photo-mov-filename-policy parameter added and original policy implemented

Live Photo assets have two components: still image and short video. icloudpd can download both and allows customizing file name of the video portion with --live-photo-mov-filename-policy parameter:

  • Use video file name the same as still image with original policy; use --file-match-policy name-id7 to avoid clashes of video file with other videos.

  • Use suffix from the still image with suffix policy: “IMG_1234_HEVC.MOV” for “IMG_1234.HEIC” still. This is default and works for HEIC still images only

Unicode

Changed in version 1.18.0: --keep-unicode-in-filenames parameter flag added with default false

Unicode characters are stripped from file names for better compatibility. icloudpd can leave them when --keep-unicode-in-filenames is specified.