# How to Safely Configure Auto-Delete and keep_icloud_recent Features in docker-icloudpd

> Safely configure auto-delete and keep_icloud_recent in docker-icloudpd. Learn to set features, define days, and bypass warnings with our guide.

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

---

**Enable `auto_delete` and `keep_icloud_recent_only` by setting them to `true` in your `.env` file, define `keep_icloud_recent_days` as an integer, and acknowledge the safety warnings by setting `warnings_acknowledged=true` to proceed past the mandatory two-minute pause.**

The docker-icloudpd container wraps the iCloud Photo Downloader (icloudpd) binary in a controlled environment where destructive operations require explicit configuration. Understanding how environment variables translate into command-line flags is essential before enabling features that permanently delete photos from your iCloud account.

## Understanding the Configuration Pipeline

docker-icloudpd orchestrates synchronization through three shell scripts that read your environment variables, enforce safety checks, and construct the final icloudpd command. The pipeline flows from `.env` file definitions through validation to command execution.

### Variable Definitions in init_config.sh

The file [`init_config.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/init_config.sh) declares all user-configurable variables at container startup. According to the source code, lines 13-15 define the parameters controlling deletion behavior:

- **`auto_delete`** – Boolean flag that defaults to `false`. When enabled, the container removes photos from iCloud that are no longer present in your local download directory.
- **`keep_icloud_recent_only`** – Boolean flag that enables retention mode, keeping only a specified number of recent days in iCloud.
- **`keep_icloud_recent_days`** – Integer value representing the number of days to retain. This parameter is only evaluated when `keep_icloud_recent_only` is set to `true`.

These variables are sourced from `/config/.env` or passed directly through Docker environment parameters.

### Command-Line Construction in sync-icloud.sh

The [`sync-icloud.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/sync-icloud.sh) script translates your environment variables into icloudpd binary flags during the synchronization phase. At lines 2199-2202, the script checks the `auto_delete` variable:

```bash

# When auto_delete is not false, append the flag

if [ "${auto_delete}" != false ]; then
   command_line+=" --auto-delete"
fi

```

For the recent-only retention policy, lines 2206-2209 implement the logic:

```bash

# If keep_icloud_recent_only is true and days are specified

if [ "${keep_icloud_recent_only}" = true ] && [ -n "${keep_icloud_recent_days}" ]; then
   command_line+=" --keep-icloud-recent-days ${keep_icloud_recent_days}"
fi

```

## Safety Mechanisms and Mandatory Warnings

Before executing any destructive operation, [`launcher.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/launcher.sh) implements a critical safety checkpoint. Lines 30-35 of this file contain warning text explaining that the "Keep iCloud recent" feature deletes all files older than the specified day count from iCloud entirely.

By default, the container enforces a **two-minute pause** upon startup when dangerous options are detected. This delay provides a window to abort the container (`Ctrl-C`) if configuration errors are discovered. To proceed past this pause, you must explicitly set `warnings_acknowledged=true` in your environment file.

## Configuration Examples

The following snippets demonstrate practical implementations. Always start with `warnings_acknowledged=false` during initial testing to verify your configuration.

### Enable Auto-Delete Only

This configuration removes photos from iCloud after confirming they exist locally:

```dotenv

# .env configuration

auto_delete=true
warnings_acknowledged=false

```

**Result:** [`sync-icloud.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/sync-icloud.sh) appends `--auto-delete` to the icloudpd command, but no retention date filtering occurs.

### Retain Only Recent Photos

To keep only the last 30 days of photos in iCloud while removing older content:

```dotenv

# .env configuration

keep_icloud_recent_only=true
keep_icloud_recent_days=30
warnings_acknowledged=false

```

**Result:** The script adds `--keep-icloud-recent-days 30` to the command line after displaying the mandatory warning in [`launcher.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/launcher.sh).

### Combined Configuration (High Risk)

**Warning:** This example demonstrates both features active simultaneously. Testing in a non-production environment is mandatory.

```dotenv

# .env configuration - USE WITH EXTREME CAUTION

auto_delete=true
keep_icloud_recent_only=true
keep_icloud_recent_days=0
warnings_acknowledged=true

```

**Result:** This deletes all photos not present locally via `--auto-delete`, then removes everything older than 0 days via `--keep-icloud_recent_days`, effectively wiping the entire iCloud photo library.

### Docker Compose Implementation

Mount your configuration file and pass variables through the environment section:

```yaml

# docker-compose.yml

services:
  icloudpd:
    image: ghcr.io/boredazfcuk/docker-icloudpd:latest
    container_name: icloudpd
    restart: unless-stopped
    environment:
      - AUTO_DELETE=true
      - KEEP_ICLOUD_RECENT_ONLY=true
      - KEEP_ICLOUD_RECENT_DAYS=7
      - WARNINGS_ACKNOWLEDGED=true
    volumes:
      - ./config:/config
      - ./photos:/photos

```

The environment keys map directly to the variables processed by [`init_config.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/init_config.sh).

## Critical Safety Considerations

Both `--auto-delete` and `--keep-icloud-recent-days` perform **irreversible deletions** from your iCloud account. Unlike local file operations, these changes sync immediately across all Apple devices linked to the account.

Setting `keep_icloud_recent_days=0` triggers immediate deletion of your entire iCloud photo library, as zero days satisfies the "older than" condition for all existing photos. Always verify your download integrity and backup strategy before enabling `warnings_acknowledged=true`.

## Summary

- **Configuration File:** [`init_config.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/init_config.sh) (lines 13-15) defines `auto_delete`, `keep_icloud_recent_only`, and `keep_icloud_recent_days` variables.
- **Command Building:** [`sync-icloud.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/sync-icloud.sh) translates these into `--auto-delete` (lines 2199-2202) and `--keep-icloud-recent-days` (lines 2206-2209) flags.
- **Safety Pause:** [`launcher.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/launcher.sh) (lines 30-35) enforces a two-minute warning period unless `warnings_acknowledged=true` is set.
- **Data Risk:** Both features permanently remove photos from iCloud; `keep_icloud_recent_days=0` deletes the entire library.

## Frequently Asked Questions

### What happens if I set keep_icloud_recent_days to 0?

Setting this value to 0 configures icloudpd to delete all photos older than 0 days, which encompasses your entire iCloud photo library. According to the implementation in [`sync-icloud.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/sync-icloud.sh), this value passes directly to the `--keep-icloud-recent-days` flag without minimum threshold validation, resulting in complete data loss if `keep_icloud_recent_only` is enabled.

### Why does the container pause for two minutes on startup?

The pause occurs in [`launcher.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/launcher.sh) when dangerous deletion features are detected and `warnings_acknowledged` is not set to `true`. This two-minute window allows you to interrupt the container with `Ctrl-C` if you discover a configuration error that would cause unintended photo deletion. The warning text explicitly states that the "Keep iCloud recent" feature deletes files permanently from iCloud.

### Can I use auto-delete without keep_icloud_recent_only?

Yes. These features operate independently. Setting `auto_delete=true` without `keep_icloud_recent_only` results in only the `--auto-delete` flag being appended to the command line (as implemented at lines 2199-2202 of [`sync-icloud.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/sync-icloud.sh)). This removes photos from iCloud only after they have been successfully downloaded and are present in your local directory, without applying any date-based retention logic.

### Where do I place the .env file in a Docker Compose setup?

The container expects environment variables at `/config/.env` inside the filesystem. In your [`docker-compose.yml`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/docker-compose.yml), mount a host directory containing the `.env` file to `/config`, or define the variables directly in the `environment:` section. The [`init_config.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/init_config.sh) script reads this location during container initialization to populate the runtime configuration.