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

> Configure your docker icloudpd photo download size to original, medium, thumb, adjusted, or alternative. Easily control your iCloud photo downloads with this guide.

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

---

**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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/docker-compose.yml):

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

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

```env

# 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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/docker-compose.yml):

```yaml
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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/init_config.sh) script (line 143) during container initialization, and [`sync-icloud.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/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.