- A command-line tool to download all your iCloud photos.
- Works on Mac, Linux, and Windows.
- Run it multiple times to download any new photos.
- I use the Photos app on my MacBook, set to "Optimize Mac Storage". It stores full-resolution images in iCloud, and only stores thumbnails on my computer until they are requested.
- I want to download a copy of all my photos onto my Linux PC, because:
- I use Plex instead of an Apple TV. Now I can display photo slideshows with Plex.
- I like having a backup of all my photos on my own hard-drive.
- I only want to download the "medium" size of all my photos. They save some space while still being big enough for slideshows. If "medium" is not available, then fall back to downloading the original size.
# Clone the repo somewhere
git clone https://github.com/ndbroadbent/icloud_photos_downloader.git
cd icloud_photos_downloader
# Install dependencies (Linux)
sudo pip install -r requirements.txt
If your account has two-factor authentication enabled, you will be prompted for a code when you run the script.
Two-factor authentication will expire after an interval set by Apple, at which point you will have to re-authenticate. This interval is currently two months.
You can receive an email notification when two-factor authentication expires by passing the
--smtp-username
and --smtp-password
options. Emails will be sent to --smtp-username
by default,
or you can send to a different email address with --notification-email
.
If you want to send notification emails using your Gmail account, and you have enabled two-factor authentication, you will need to generate an App Password at https://myaccount.google.com/apppasswords
You can store your password in the system keyring using the icloud
command-line tool
(installed with the pyicloud
dependency):
$ icloud [email protected]
ICloud Password for [email protected]:
Save password in keyring? (y/N)
If you have stored a password in the keyring, you will not be required to provide a password when running the script.
If you would like to delete a password stored in your system keyring,
you can clear a stored password using the --delete-from-keyring
command-line option:
$ icloud [email protected] --delete-from-keyring
$ ./download_photos.py <download_directory>
--username=<username>
[--password=<password>]
[--size=(original|medium|thumb)]
[--recent <integer>]
[--until-found <integer>]
[--download-videos]
[--auto-delete]
[--only-print-filenames]
[--smtp-username <smtp_username>]
[--smtp-password <smtp_password>]
[--smtp-host <smtp_host>]
[--smtp-port <smtp_port>]
[--smtp-no-tls]
[--notification-email <notification_email>]
[--loop]
[--loop-delay <integer>]
Options:
--username <username> Your iCloud username or email address
--password <password> Your iCloud password
--size [original|medium|thumb] Image size to download (default: original)
--recent INTEGER RANGE Number of recent photos to download
(default: download all photos)
--until-found INTEGER RANGE Download most recently added photos until we
find x number of previously downloaded
consecutive photos (default: download all
photos)
--download-videos Download both videos and photos (default:
only download photos)
--force-size Only download the requested size (default:
download original if size is not available)
--auto-delete Scans the "Recently Deleted" folder and
deletes any files found in there. (If you
restore the photo in iCloud, it will be
downloaded again.)
--only-print-filenames Only prints the filenames of all files that
will be downloaded. (Does not download any
files.)
--smtp-username <smtp_username>
Your SMTP username, for sending email
notifications when two-step authentication
expires.
--smtp-password <smtp_password>
Your SMTP password, for sending email
notifications when two-step authentication
expires.
--smtp-host <smtp_host> Your SMTP server host. Defaults to:
smtp.gmail.com
--smtp-port <smtp_port> Your SMTP server port. Default: 587 (Gmail)
--smtp-no-tls Pass this flag to disable TLS for SMTP (TLS
is required for Gmail)
--notification-email <notification_email>
Email address where you would like to
receive email notifications. Default: SMTP
username
--loop Flag that indicates the process should continuously run in a loop with a delay
--loop_delay The number of seconds to wait between each iteration
-h, --help Show this message and exit.
Example:
$ ./download_photos.py ./Photos \
[email protected] \
--password=pass1234 \
--size=original \
--recent 500 \
--auto-delete
The first time you run the script, you will probably see an error message like this:
Bad Request (400)
This error usually means that Apple's servers are getting ready to send you data about your photos. This process can take around 5-10 minutes, so please wait a few minutes, then try again.
(If you are still seeing this message after 30 minutes, then please open an issue on GitHub.)
cp cron_script.sh.example cron_script.sh
-
Edit cron_script.sh with your username, password, and other options
-
Run
crontab -e
, and add the following line:
0 */3 * * * /path/to/icloud_photos_downloader/cron_script.sh
- Build the image:
$ git clone https://github.com/ndbroadbent/icloud_photos_downloader.git
$ cd icloud_photos_downloader.git/docker
$ docker build -t icloud_photos_downloader .
- Usage:
$ docker run -it --rm --name icloud -v $(pwd)/Photos:/data icloud_photos_downloader ./download_photos.py \
[email protected] \
--password=pass1234 \
--size=original \
--recent 500 \
--auto-delete \
/data