iCloud Photos Downloader (icloudpd)

You can process multiple iCloud accounts or apply different settings to the same account by repeating the --username parameter.

Rules for parameters:

• Parameters specified before the first --username act as defaults for all subsequent users.
• Parameters specified after a --username apply only to that specific user/config.
• Global app-wide settings can be placed anywhere.

# Example: Two different user accounts
$ icloudpd --use-os-locale --cookie-directory ./cookies --username alice@apple.com --directory ./alice --username bob@apple.com --directory ./bob

# Example: Two different configurations for the same account
$ icloudpd --cookie-directory ./cookies --username alice@apple.com --directory ./photos --skip-videos --username alice@apple.com --directory ./videos --skip-photos --use-os-locale

The tool operates in three distinct modes to manage how photos are handled between iCloud and your local system:

• Copy (Default): Downloads new photos from iCloud to your local directory.
• Sync: Downloads new photos from iCloud and deletes local files that have been removed from iCloud (requires the --auto-delete option).
• Move: Downloads new photos from iCloud and deletes the photos from iCloud (requires the --keep-icloud-recent-days option).

The icloudpd tool operates in one of three modes depending on how you want to manage the relationship between your local storage and iCloud.

1. Copy (Default): Downloads assets from iCloud that are missing from your local storage. It does not modify anything in iCloud or delete local files.
2. Sync: Downloads missing assets from iCloud and also deletes local files that have been removed from iCloud (e.g., moved to the 'Recently Deleted' album). This is activated using the --auto-delete parameter.
3. Move: Downloads missing assets from iCloud and then deletes the assets from iCloud that are already present in your local storage. You can optionally configure this to leave recent assets in iCloud using the --keep-icloud-recent-days parameter.

Use npx to run the tool without a permanent installation.

npx --yes icloudpd --directory /data --username my@email.address --watch-with-interval 3600

Install the package using pip.

Windows: It is recommended to use the --user flag:

pip install icloudpd --user

Note: You must add the Python Scripts directory (e.g., C:\Users\<YourUserAccountHere>\AppData\Roaming\Python\Python<Version>\Scripts) to your PATH. The exact path is displayed at the end of installation.

macOS: You must add the Python bin directory (e.g., /Users/<YourUserAccountHere>/Library/Python/<Version>/bin) to your PATH.

If you do not have Python and Pip installed on macOS, you have two primary options:

Option 1: Apple Command Line Tools

Install the Xcode Command Line Tools via the terminal:

xcode-select --install

Then, use pip3 to install the downloader:

pip3 install icloudpd

Option 2: Homebrew

If you use Homebrew, install Python (which includes pip) using:

brew install python

To install Python on Ubuntu, use the following commands:

sudo apt-get update
sudo apt-get install -y python

You can run icloudpd using one of three methods:

1. Direct Executable: Download the platform-specific executable from the GitHub Releases page and run it.
2. Package Managers: Install via Docker, PyPI, AUR, or npm.
3. Source: Build and run directly from the source code.

Starting from version 1.21.0, icloudpd can launch an internal web server on port 8080. This allows you to provide your iCloud password and Multi-Factor Authentication (MFA) code via a web interface instead of using the command line console.

To enable this, you must select webui as the provider for either the MFA provider or the Password Provider in your configuration.

# Note: The web server is started only if `webui` is selected for MFA provider and/or Password Provider

The Intel 64-bit binary works on both Intel and Apple Silicon (M1, M2, M3) Macs. Follow these steps to bypass macOS security restrictions:

1. Download the binary from GitHub Releases.
2. Make it executable: chmod +x <binary_name>.
3. Run it from the terminal.
4. When Apple blocks it, go to System Settings > Privacy & Security and click 'Allow' for the blocked app.
5. Run it again and click 'Open' when prompted.

chmod +x icloudpd-1.32.3-macos-amd64
./icloudpd-1.32.3-macos-amd64