Skip to content
Get packs

Guide · Open source

How to use icloud_photos_downloader (icloudpd) to back up iCloud Photos

Updated · written with AI from the project's own documentation and checked against our catalogue data

icloud_photos_downloader is a free, open-source command-line tool, installed as icloudpd, that copies your photos and videos from iCloud to a folder you choose. This guide covers the iCloud account settings you need first, the basic run command, how to keep the folder updated, and the main modes it supports. It is written for people comfortable typing commands in a terminal, such as owners of a laptop, desktop, or NAS who want a local copy of their iCloud Photos library.

iCloud Photos Downloadericloud-photos-downloader/icloud_photos_downloader · ★ 12.4k · MIT

Quick start

  1. 1Check iCloud settings. Enable Access iCloud Data on the Web and either disable Advanced Data Protection or plan to use --adp-web-access.
  2. 2Install icloudpd. Choose an executable, a package manager such as PyPI, or build from source as described in the project documentation.
  3. 3Pick a local folder. Decide where the photos should be saved and pass it with --directory.
  4. 4Run a first sync. Run icloudpd with --directory, --username, and --watch-with-interval, then complete the password and any 2FA prompts.
  5. 5Verify the session. Use --auth-only to confirm the session is still authenticated when needed.
  6. 6Review the options. Run icloudpd --help and read the modes before enabling Sync or Move, since those can delete files.

Check the iCloud settings before you start

The README says that if your iCloud account is not configured correctly, Apple's servers will return an ACCESS_DENIED error. Two settings matter. First, enable Access iCloud Data on the Web on your iPhone or iPad under Settings > Apple ID > iCloud. Second, handle Advanced Data Protection (ADP): either disable it under Settings > Apple ID > iCloud > Advanced Data Protection, or keep it enabled and run the tool with --adp-web-access.

  • Enable Access iCloud Data on the Web: Settings > Apple ID > iCloud > Access iCloud Data on the Web
  • Advanced Data Protection: disable it, or keep it on and add --adp-web-access

Install icloudpd

The README lists three ways to run icloudpd: download an executable for your platform from the GitHub Releases page and run it; use a package manager (Docker, PyPI, AUR, or npm); or build and run from the source. It works on Linux, Windows, and macOS. The README excerpt does not show the exact PyPI install command or the Python version required, so check the project documentation for those details.

The README also gives a git clone URL for the repository: https://github.com/icloud-photos-downloader/icloud_photos_downloader

git clone https://github.com/icloud-photos-downloader/icloud_photos_downloader

Run your first sync to a local folder

The README's usage example keeps an iCloud photo collection synchronized to a local folder and checks for new items every 3600 seconds. Replace /data with the folder you want to use and use your own Apple ID email address. The tool prompts for your password and any two-step verification if needed, based on the README's note about 2SA/2FA validation.

  • --directory sets the local folder where files are saved
  • --username is your Apple ID email
  • --watch-with-interval 3600 keeps the tool running and checking iCloud every hour
  • The command is icloudpd, not icloud
icloudpd --directory /data --username my@email.address --watch-with-interval 3600

Create and verify a session with --auth-only

To create and authorize a session separately, including completing 2SA/2FA validation if needed, use the --auth-only option. The README notes you can run this again to check that the session is still authenticated. Be aware that this example passes the password on the command line, which may be visible in your shell history.

  • Use --auth-only to set up or re-check the session
  • Run --help to see the full list of options
icloudpd --username my@email.address --password my_password --auth-only

Choose a mode: copy, sync, or move

The default mode is Copy, which downloads new photos from iCloud. Sync also deletes local files that were removed in iCloud, enabled with --auto-delete. Move downloads new photos and then deletes photos in iCloud, controlled by --keep-icloud-recent-days. Read the mode carefully before you use Sync or Move, because both can delete files.

  • Copy (default): download new photos
  • Sync: add --auto-delete to remove local files deleted in iCloud
  • Move: use --keep-icloud-recent-days; this deletes photos in iCloud

Other features the README mentions

The README lists handling for Live Photos (image and video as separate files) and RAW images, including RAW+JPEG. It also automatically de-duplicates photos with the same name, supports incremental runs with --until-found and --recent, and can update EXIF date/time with --set-exif-datetime. The README says there are many more options; run icloudpd --help for the full list.

  • Live Photos saved as separate image and video files
  • RAW and RAW+JPEG support
  • Incremental runs with --until-found and --recent
  • EXIF date/time updates with --set-exif-datetime
icloudpd --help

What people use it for

  • Keeping a local backup of an iCloud Photos library on a laptop or desktop
  • Automatically syncing photos to a NAS or home server with --watch-with-interval
  • Keeping Live Photos and RAW files as separate files for later editing
  • Running a periodic check of iCloud changes with incremental options such as --recent

Frequently asked questions

Is icloud_photos_downloader free?

The project is released under the MIT licence, as stated in the README and the license badge. It is developed and maintained by volunteers, and the README says the project is currently looking for a maintainer.

What is the command to run icloudpd?

The README's example is icloudpd --directory /data --username my@email.address --watch-with-interval 3600. The executable is named icloudpd, not icloud.

Why do I get an ACCESS_DENIED error?

The README says Apple servers return ACCESS_DENIED when the iCloud account is not configured correctly. Enable Access iCloud Data on the Web and either disable Advanced Data Protection or run with --adp-web-access.

Does it work on a NAS?

The README says it works on Linux, Windows, and macOS across laptops, desktops, and NAS devices, and it lists Docker as one of the package manager options.

Can it delete my photos?

Yes, in some modes. Sync (--auto-delete) deletes local files removed in iCloud, and Move (--keep-icloud-recent-days) deletes photos in iCloud. The default Copy mode only downloads new photos.

What are the alternatives?

The comparable projects listed for this item are osxphotos and icloudpy. The source excerpt does not compare them in detail, so review each project's documentation before choosing.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

icloudpd suits people who are comfortable in a terminal and want a free, scriptable local copy of their iCloud Photos, especially on a NAS or home server. It is not a good fit for anyone who is uncomfortable with command-line tools, cannot change iCloud account settings, or needs a supported, funded product, since the project is volunteer-run and currently seeking a maintainer.

Install options & downloads