PyiCloud

PyiCloud is a module which allows pythonistas to interact with iCloud webservices. It's powered by the fantastic requests HTTP library.

At its core, PyiCloud connects to the iCloud web application using your username and password, then performs regular queries against its API.

Please see the terms of use for your responsibilities when using this library.

For support and discussions, join our Discord community: Join our Discord community

Installation

Install the library and CLI with:

$ pip install "pyicloud[cli]"

This installs the icloud command line interface alongside the Python package. To install the library on its own run pip without the cli extra.

$ pip install pyicloud

Authentication

Authentication without using a saved password is as simple as passing your username and password to the PyiCloudService class:

from pyicloud import PyiCloudService

api = PyiCloudService("jappleseed@apple.com", "password")

In the event that the username/password combination is invalid, a PyiCloudFailedLoginException exception is thrown.

For China mainland accounts, long-running daemon settings, family polling, pause_2fa, and the full two-step / two-factor (2SA/2FA) flow, see the Authentication guide. The icloud CLI can also store your password in the system keyring; see the Command-Line Interface guide.

Documentation

Full documentation lives under docs/. It is also published, with a generated API reference, at pyicloud.readthedocs.io.

Guides

• Authentication — login, pause_2fa, and 2SA/2FA
• Command-Line Interface — the icloud command, auth/session management, and keyring storage
• Diagnostics — icloud doctor and its exit codes

Services

• Account — account info, storage, and summary plan
• Devices & Find My — list devices and locate, ring, lock, or erase them
• Calendar — calendars, events, alarms, and invitees
• Contacts — the address book and MeCard
• File Storage (Drive) — iCloud Drive and the legacy Ubiquity API
• Photos — browse, sync, upload, and modify the photo library
• Hide My Email — generate and manage email aliases
• Reminders — lists, reminders, alarms, tags, and attachments
• Notes — folders, note rendering, and HTML export
• Invites — read events and respond to invitations

Examples

If you want to see some code samples, see the examples.

Contributing

Contributions are welcome! Please read the Contributing guide, the Code of Conduct, and the Terms of Use before getting started.

To report a security vulnerability, use private vulnerability reporting rather than opening a public issue (see SECURITY.md).