How to Download Specific Albums or Shared Libraries with docker-icloudpd

Set the photo_album or photo_library variables in /config/icloudpd.conf to comma-separated lists of names, or use "all albums" and "all libraries" to select everything, then restart the container to download only those specific collections.

docker-icloudpd is a containerized wrapper around the upstream iCloud Photos Downloader (icloudpd) binary. Instead of downloading your entire iCloud photo library, you can configure selective downloads using the wrapper script [sync-icloud.sh](https://github.com/boredazfcuk/docker-icloudpd/blob/master/sync-icloud.sh) to target specific albums or shared libraries only.

Configuration Variables for Selective Downloads

The wrapper reads environment variables and the configuration file /config/icloudpd.conf to build the command-line arguments passed to icloudpd.

Downloading Specific Albums with photo_album

The photo_album variable accepts a comma-separated list of album names. When set, the wrapper passes --album "<value>" to the icloudpd binary.

• Set photo_album="Vacation 2023,Family Reunion" to download only those two albums.
• Set photo_album="all albums" to download every album individually (the wrapper expands this internally).

In sync-icloud.sh, the check_files function (around line 3220) handles the --album flag construction.

Downloading Shared Libraries with photo_library

The photo_library variable targets shared libraries (the collaborative collections introduced in iOS 16). It accepts a comma-separated list of library names or "all libraries".

• Set photo_library="FamilyShared,WorkShared" to download only those shared libraries.
• Set photo_library="all libraries" to download every shared library available to the account.

The wrapper resolves the list via the resolve_library_list function (around line 887) and invokes icloudpd with --library "<value>" for each entry in the download_libraries loop.

How the Wrapper Script Processes Selections

Understanding the internal flow helps troubleshoot configuration issues.

1. Configuration Loading: On startup, sync-icloud.sh sources /config/icloudpd.conf (source "${config_file}" at line 18).
2. Album/Library Resolution: If photo_library is set to "all libraries", the script calls icloudpd --list-libraries to build a comma-separated list (resolve_library_list). The same pattern applies for albums when photo_album is "all albums" (handled in download_albums).
3. Download Loop: For each album (and optionally each library), the script builds the final icloudpd command, adding --album and/or --library flags, and executes it via the run_as helper (which switches to the non-root user inside the container).
4. Result Handling: Downloaded files are logged to /tmp/icloudpd/icloudpd_sync.log, and notifications are sent based on the configured notification backend.

Listing Available Albums and Libraries

Before configuring selective downloads, you must know the exact names of your albums and shared libraries. The wrapper provides helper commands to list them.

List All Albums

Run the following command to see every album available to your Apple ID:

docker exec -it <container_name> sync-icloud.sh --List-Albums

This invokes the list_albums() function in sync-icloud.sh (lines 520-540), which calls icloudpd --list-albums and formats the output.

List All Shared Libraries

To discover the names of shared libraries you have access to:

docker exec -it <container_name> sync-icloud.sh --List-Libraries

This uses the list_libraries() function (lines 498-514) to query icloudpd --list-libraries.

Copy the exact names from these outputs into your photo_album or photo_library configuration.

Practical Configuration Examples

Example 1: Edit the Configuration File

The most persistent method is editing the configuration file directly:

# Access the container or the bind-mounted config volume

docker exec -it icloudpd vi /config/icloudpd.conf

Add or modify these lines:

photo_album="Vacation 2023,Family Reunion"
photo_library="FamilyShared"

Restart the container to apply changes:

docker restart icloudpd

Example 2: Use Environment Variables

For a quick one-off or when using docker run, pass variables as environment variables:

docker run -d \
  --name icloudpd \
  -v icloudpd_config:/config \
  -e TZ=Europe/London \
  -e photo_album="Trip to Japan" \
  -e photo_library="FriendsShared" \
  boredazfcuk/icloudpd

The script reads environment variables before sourcing the config file, so these take precedence.

Example 3: Combine Albums and Libraries

You can download specific albums from specific shared libraries by combining both variables:

# /config/icloudpd.conf

photo_album="Birthday Party,Wedding"
photo_library="FamilyShared,WorkShared"

The wrapper will process each album against each library (unless filtered by skip_library or skip_album settings), creating a matrix of downloads.

Summary

• Selective downloading in docker-icloudpd is controlled by the photo_album and photo_library configuration variables.
• The wrapper script sync-icloud.sh translates these variables into --album and --library flags for the upstream icloudpd binary.
• Use docker exec <container> sync-icloud.sh --List-Albums and --List-Libraries to discover exact names before configuring.
• Configuration can be set persistently in /config/icloudpd.conf or temporarily via environment variables.
• The special values "all albums" and "all libraries" trigger automatic expansion to download every available collection.

Frequently Asked Questions

How do I find the exact names of my iCloud albums to use with docker-icloudpd?

Run the discovery command inside your running container: docker exec -it <container_name> sync-icloud.sh --List-Albums. This executes the list_albums() function in sync-icloud.sh (lines 520-540) and outputs the exact album names recognized by iCloud. Copy these names exactly—including spaces and capitalization—into your photo_album configuration.

Can I download from both specific albums and shared libraries at the same time?

Yes. Set both photo_album and photo_library in your configuration file. The wrapper script processes each combination: for every album listed in photo_album, it will attempt to download from every library listed in photo_library (unless excluded by skip_album or skip_library filters). This is handled in the download_albums and download_libraries functions within sync-icloud.sh.

What happens if I set photo_album to "all albums"?

When photo_album is set to the literal string "all albums", the wrapper script does not pass that string directly to icloudpd. Instead, the download_albums function queries iCloud for every album name and expands the value into a comma-separated list. It then iterates through each album individually, invoking icloudpd with the --album flag for each one. This ensures every album is downloaded without manually listing them.

Is it possible to override the album or library selection without editing the config file?

Yes. You can pass environment variables directly when running the container. The sync-icloud.sh script reads environment variables before sourcing /config/icloudpd.conf, so values provided via -e photo_album="Album Name" or -e photo_library="Library Name" in your docker run command will override the file-based configuration. This is useful for testing specific downloads without permanently changing your configuration.

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