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

Linux binaries

Linux binaries are available for amd64, arm64 and arm32v7, in two variants:

  • icloudpd-<version>-linux-<arch> for distributions based on glibc, e.g. Debian, Ubuntu, Fedora

  • icloudpd-<version>-linux-musl-<arch> for distributions based on musl, e.g. Alpine

The musl variant needs musl 1.2.5 or newer, which is Alpine 3.20 and newer. On older Alpine releases it fails to start (Error relocating ... or a segmentation fault). The same applies to the musl wheels on PyPI (musllinux), which contain the same binary.

macOS binary

icloudpd is available as a binary for Apple Silicon Macs (icloudpd-<version>-macos-arm64) and for Intel Macs (icloudpd-<version>-macos-amd64). The Intel binary is built for as long as GitHub provides Intel macOS build machines; on Intel Macs after that, use Docker or PyPI.

Note

In 1.32.3, icloudpd-1.32.3-macos-amd64 was built for Apple Silicon by mistake and does not run on Intel Macs (bad CPU type in executable). Use 1.32.2 or a later release on Intel Macs.

Here are the steps to make it work (the examples use the Apple Silicon binary):

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

  • Add the executable flag by running chmod +x icloudpd-1.33.0-macos-arm64

  • Start it from the terminal: icloudpd-1.33.0-macos-arm64

  • 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.33.0-macos-arm64 as a blocked app; click “Allow”

  • Start icloudpd-1.33.0-macos-arm64 from the terminal again

  • Apple will show another warning; click “Open”

  • After that, you can run icloudpd-1.33.0-macos-arm64 --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.