iCloud Authentication¶
Two programs: icloudpd and icloud
icloudpddownloads your photos. Use it for everything on this page, including signing in (see--auth-only).icloudis a small extra tool that comes withicloudpd(its help text says “Find My iPhone CommandLine Tool”). It is only useful to save your password in the system keyring or to delete it from there, see Managing System Keyring.
Both use the same keyring entry, but icloud keeps its session in a different folder (pyicloud/<your login name> in the system temporary folder, on Linux usually /tmp/pyicloud/<your login name>) and has no --cookie-directory option. Signing in or entering a 2FA code with icloud therefore does not sign in icloudpd.
Multi-Factor Authentication¶
If your Apple account has two-factor authentication (multi-factor authentication, MFA) 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. Apple requires MFA for all new accounts.
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.
MFA Providers¶
Added in version 1.21.0.
There are two ways to provide an MFA code to icloudpd:
Using console
Using web interface
The choice can be made with --mfa-provider parameter.
Default: console Other options: webui
The 2FA Code Doesn’t Arrive¶
icloudpd asks Apple to send the code to your trusted Apple devices. If it doesn’t show up there, the console can send it by SMS instead. If your account has trusted phone numbers, they are listed with a letter before the prompt, for example:
a: (•••) •••-••12
Please enter two-factor authentication code or device index (a) to send SMS with a code:
Type the letter of a number (here a) instead of the code. icloudpd sends an SMS to that number and asks for the code that you received over SMS.
The Web UI only has a field for the code and cannot send an SMS. If you normally use webui, sign in once in the console with --auth-only and the same --cookie-directory; in Docker, add -it to docker run so you can type in the console.
Access from Mainland China¶
Access to iCloud.com is blocked from mainland China. icloudpd can be used with the --domain cn parameter to support downloading iCloud Photos from mainland China; however, people have reported mixed results with that parameter.
FIDO¶
Added in version 1.33.0.
Accounts with security keys (FIDO, e.g. YubiKey) don’t get a six-digit code. icloudpd asks for one of the registered keys instead, which must be plugged into the machine running icloudpd.
To use icloudpd on a machine without the key, sign in once with --auth-only where the key is and copy the --cookie-directory over.
The webui MFA provider does not support security keys.
ADP¶
Added in version 1.33.0.
Accounts with Advanced Data Protection (ADP) can be used with the --adp-web-access parameter. It replays the consent sequence that icloud.com performs before showing photos, so it requires Settings > [your name] > iCloud > Access iCloud Data on the Web to be enabled on the Apple device.
The first run sends an approval notification to your Apple devices and waits up to two minutes for it to be accepted. Once approved, later runs (including from other machines or cookie directories) do not ask again.
Without the parameter, an ADP account fails with ACCESS_DENIED.
Occasional Errors¶
Some authentication errors may be resolved by deleting the session folder, so that icloudpd signs in from scratch (you will be asked for a 2FA code again). Example
The session folder is:
the folder given with
--cookie-directory, if you set one;otherwise
~/.pyicloud(on WindowsC:\Users\<you>\.pyicloud);inside Docker without
--cookie-directory:/root/.pyicloudin the container.
To sign in again for one account only, delete just its two files: the file name is the Apple ID with everything except letters, digits and _ removed, e.g. jappleseedapplecom and jappleseedapplecom.session for jappleseed@apple.com.
Password Providers¶
Added in version 1.20.0.
Added in version 1.21.0: WebUI support
Passwords for iCloud access can be supplied by the user in four ways:
Using
--passwordcommand line parameterUsing keyring
Using console
Using web interface
It is possible to specify which of these four ways icloudpd should use, by specifying them with the --password-provider parameter. More than one can be specified and the order
of providers matches the order they will be checked for a password. E.g., --password-provider keyring --password-provider console means that icloudpd will check the password in the keyring first and then, if no password is found, ask for a password in the console.
The keyring password provider, if specified, saves the valid password back into the keyring.
Console and Web UI are not compatible with each other. Console or WebUI providers, if specified, must be last in the list of providers because they cannot be skipped.
Default set and order of providers are: parameter, keyring, console
Managing System Keyring¶
When keyring is one of the password providers (it is by default), icloudpd saves the password in the system keyring after a successful sign-in, so later runs don’t ask for it again.
You can also store your password in the system keyring, or delete it from there, using the icloud command-line tool:
$ icloud --username jappleseed@apple.com
Enter iCloud password for jappleseed@apple.com:
Save password in keyring? [y/N]
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 --username jappleseed@apple.com --delete-from-keyring
After deleting the password, icloud continues and asks for the password to sign in. Press Ctrl+C if you only wanted to delete it.
Note
Use icloud, not icloudpd
Keyring on Servers and in Docker¶
On a machine without a desktop keyring (a headless Linux server, a NAS, or the Docker image), the keyring falls back to a plain text file, ~/.local/share/python_keyring/keyring_pass.cfg (in Docker: /root/.local/share/python_keyring/keyring_pass.cfg in the container). The password in that file is not encrypted.
If you don’t want the password stored on disk, leave keyring out of the password providers, e.g. use --password-provider console or --password-provider webui. A password that is already stored can be deleted with icloud --delete-from-keyring (see above).
Using Multiple Accounts and Config¶
icloudpd can process iCloud collections for multiple accounts or use multiple configs for one account. This is achieved by specifying the --username parameter multiple times: any options specified after --username will be applied to the mentioned user only. Parameters specified before the first --username work as defaults for all other user configs. Global app-wide settings can be specified anywhere. These are the global settings:
--help,--version--log-level--threads-num(deprecated, has no effect)
All other parameters can be set per user.
Example: using two user accounts¶
$ icloudpd --use-os-locale --cookie-directory ./cookies --username alice@apple.com --directory ./alice --username bob@apple.com --directory ./bob
Explanation
--use-os-localeis a global parameter and can be used anywhere--cookie-directoryis a default for both users; it is okay to use the same folder since sessions and cookies are stored in files based on the user name, so they would not collide--directory ./alicespecifies that all photos for Alice will be downloaded into the ./alice folder--directory ./bobspecifies that all photos for Bob will be downloaded into the ./bob folder
Example: using two configs for one account¶
$ icloudpd --cookie-directory ./cookies --username alice@apple.com --directory ./photos --skip-videos --username alice@apple.com --directory ./videos --skip-photos --use-os-locale
Explanation
--cookie-directoryis a default for both configs--directory ./photos --skip-videosspecifies that all photos for Alice will be downloaded into the ./photos folder--directory ./videos --skip-photosspecifies that all videos for Alice will be downloaded into the ./videos folder--use-os-localeis a global parameter and can be used anywhere
Added in version 1.32.0.