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

> Learn how to download specific albums or shared libraries with docker-icloudpd. Configure photo album or library variables to select only desired collections.

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

---

**Set the `photo_album` or `photo_library` variables in [`/config/icloudpd.conf`](https://github.com/boredazfcuk/docker-icloudpd/blob/main//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/main/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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main//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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/sync-icloud.sh) sources [`/config/icloudpd.conf`](https://github.com/boredazfcuk/docker-icloudpd/blob/main//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:

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

```

This invokes the `list_albums()` function in [`sync-icloud.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/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:

```bash
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:

```bash

# Access the container or the bind-mounted config volume

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

```

Add or modify these lines:

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

```

Restart the container to apply changes:

```bash
docker restart icloudpd

```

### Example 2: Use Environment Variables

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

```bash
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:

```text

# /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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main//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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/sync-icloud.sh) script reads environment variables before sourcing [`/config/icloudpd.conf`](https://github.com/boredazfcuk/docker-icloudpd/blob/main//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.