How to Configure Photo Download Size in Docker iCloudPD: Original, Medium, Thumb, Adjusted, and Alternative

Set the photo_size environment variable to original, medium, thumb, adjusted, or alternative (or a comma-separated combination) when deploying the boredazfcuk/docker-icloudpd container.

The Docker iCloudPD image provides granular control over which photo assets are downloaded from iCloud through configurable environment variables. By adjusting these settings in your container deployment, you can optimize storage usage and download only the specific renditions you need, from full-resolution originals to compressed thumbnails.

Understanding Photo Size Options in Docker iCloudPD

The container distinguishes between standard photos and Live Photos, each with specific size options controlled via separate environment variables.

Standard Photo Sizes (photo_size)

The photo_size variable accepts any single value or comma-separated list of the following options:

• original — The full-resolution asset as stored in iCloud (default)
• medium — A medium-quality compressed version
• thumb — A thumbnail-sized rendition
• adjusted — Edited versions of photos (cropped, filtered, or otherwise modified)
• alternative — Alternative formats or renditions available for the asset

When multiple values are specified (e.g., original,adjusted), the underlying icloudpd client downloads each specified size for every photo.

Live Photo Sizes (live_photo_size)

For Live Photo components (the video portion), use the live_photo_size variable:

• original — Full-quality Live Photo video (default)
• medium — Compressed video quality
• thumb — Low-resolution video preview

How to Configure Photo Download Size Environment Variables

You can set these variables using Docker Compose, docker run commands, or environment files.

Docker Compose Configuration

Create or modify your docker-compose.yml:

services:
  icloudpd:
    image: ghcr.io/boredazfcuk/docker-icloudpd:latest
    environment:
      - PHOTO_SIZE=original,adjusted,alternative
      - LIVE_PHOTO_SIZE=medium
    volumes:
      - ./photos:/photos
    restart: unless-stopped

Docker Run Command

Deploy the container directly with size specifications:

docker run -d \
  --name icloudpd \
  -e PHOTO_SIZE="original,medium,thumb" \
  -e LIVE_PHOTO_SIZE="original" \
  -v $(pwd)/icloud_photos:/photos \
  ghcr.io/boredazfcuk/docker-icloudpd:latest

Environment File Configuration

For cleaner management, use a .env file:

# Photo size options: original, medium, thumb, adjusted, alternative

PHOTO_SIZE=original,adjusted

# Live Photo size options: original, medium, thumb

LIVE_PHOTO_SIZE=medium

Reference it in your docker-compose.yml:

services:
  icloudpd:
    env_file:
      - .env

How the Container Processes Size Configuration

The configuration logic resides in two key scripts within the repository.

In sync-icloud.sh (the container entrypoint), the script parses the photo_size environment variable and constructs the command line for the underlying icloudpd Python client. When processing sizes, the script iterates through comma-separated values and appends a --size <value> flag for each specified size (lines 2154–2171). Similarly, live_photo_size is translated to --live-photo-size <value>.

If photo_size is unset, the script defaults to original and logs a configuration warning (line 2174). These defaults are initially established by init_config.sh during container initialization, which writes photo_size=original (line 143) and live_photo_size=original (line 118) to the configuration file if no user values are provided.

The official CONFIGURATION.md documents these options in detail (lines 64–68), confirming the accepted values and default behaviors.

Summary

• Set photo_size to control which standard photo renditions are downloaded: original, medium, thumb, adjusted, or alternative.
• Set live_photo_size specifically for Live Photo video components: original, medium, or thumb.
• Both variables accept comma-separated lists to download multiple sizes simultaneously.
• The sync-icloud.sh entrypoint translates these environment variables into --size flags for the icloudpd client.
• Defaults are original for both variables, established by init_config.sh if not explicitly configured.

Frequently Asked Questions

What is the default photo download size if I don't specify anything?

If you do not set the photo_size environment variable, the container defaults to original. This default is established by the init_config.sh script (line 143) during container initialization, and sync-icloud.sh (line 2174) will log a warning that it is falling back to the original size.

Can I download multiple photo sizes simultaneously?

Yes. Both photo_size and live_photo_size accept comma-separated values. For example, setting PHOTO_SIZE=original,adjusted,alternative instructs the container to download all three renditions for every photo. The sync-icloud.sh script parses this string and appends separate --size flags for each value when invoking the icloudpd client.

What is the difference between adjusted and alternative sizes?

The adjusted size refers to photos that have been modified within the Apple ecosystem—such as crops, filters, or edits applied via the Photos app. The alternative size refers to alternative renditions or formats that may be available for certain assets, which could include different encodings or versions generated by iCloud. Both options allow you to retrieve variants beyond the unmodified original file.

How do I verify my size configuration is working correctly?

Check the container logs during startup. The sync-icloud.sh script logs the configured photo sizes before invoking the download command. If you see lines indicating --size original (or your chosen values) in the command construction, the configuration is active. Additionally, inspect your download directory—if you specified multiple sizes, you should see corresponding file variants or directories containing the different renditions.

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