Install and Run

There are three ways to run icloudpd:

  1. Download executable for your platform from the GitHub Release and run it, e.g.:

    icloudpd --username your@email.address --directory photos --watch-with-interval 3600

  2. Use a package manager to install, update, and, in some cases, run (Docker, PyPI, AUR, npm)

  3. Build and run from source

Docker

docker run -it --rm --name icloudpd -v $(pwd)/Photos:/data -e TZ=America/Los_Angeles icloudpd/icloudpd:latest icloudpd --directory /data --username my@email.address --watch-with-interval 3600

The image asset date will be converted to the specified TZ and then used for creating folders (see the --folder-structure parameter).

The synchronization logic can be adjusted with command-line parameters. Run the following to get the full list:

docker run -it --rm icloudpd/icloudpd:latest icloudpd --help

Note

On Windows:

  • use %cd% instead of $(pwd)

  • or full path, e.g. -v c:/photos/icloud:/data

  • only Linux containers are supported

Note

Getting Docker:

  • On Windows and Mac Docker is available as Docker Desktop app.

  • On Linux, Docker engine and client can be installed using platform package managers, e.g. Installing on Ubuntu

  • Appliances (e.g., NAS) will have their own way to install Docker engines and run containers - see the manufacturer’s instructions.

PyPI

Install:

pip install icloudpd

Run:

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

Note

on Windows:

pip install icloudpd --user

Also add C:\Users\<YourUserAccountHere>\AppData\Roaming\Python\Python<YourPythonVersionHere>\Scripts to PATH. The exact path will be given at the end of the icloudpd installation.

Note

on MacOS:

Add /Users/<YourUserAccountHere>/Library/Python/<YourPythonVersionHere>/bin to PATH. The exact path will be given at the end of icloudpd installation.

AUR

AUR packages can be installed on Arch Linux. Installation can be done manually or with the use of an AUR helper.

The manual process would look like this:

git clone https://aur.archlinux.org/icloudpd-bin.git
cd icloudpd-bin
makepkg -sirc

With the use of an AUR helper, e.g., yay, the installation process would look like this:

yay -S icloudpd-bin

npm

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

macOS binary

icloudpd is available as an Intel 64-bit binary for macOS, but works on ARM Macs too (M1, M2, M3).

Here are the steps to make it work:

  • Download the binary from GitHub Releases into the desired local folder

  • Add the executable flag by running chmod +x icloudpd-1.32.2-macos-amd64

  • Start it from the terminal: icloudpd-1.32.2-macos-amd64

  • Apple will tell you that it cannot check for malicious software and refuse to run the app; click “OK”

  • Open “System Settings”/”Privacy & Security” and find icloudpd-1.32.2-macos-amd64 as a blocked app; click “Allow”

  • Start icloudpd-1.32.2-macos-amd64 from the terminal again

  • Apple will show another warning; click “Open”

  • After that, you can run icloudpd-1.32.2-macos-amd64 --help or any other supported command/option

Error on the First Run

When you run the script for the first time, you might see an error message like this:

Bad Request (400)

This error often happens because your account hasn’t used the iCloud API before, so Apple’s servers need to prepare some information about your photos. This process can take around 5-10 minutes, so please wait a few minutes and try again.

If you are still seeing this message after 30 minutes, then please open an issue on GitHub and post the script output.