How icloud-photos-downloader/icloud_photos_downloader works
icloudpd is a command-line iCloud Photos downloader. The main workflow parses options, authenticates the account (including MFA), queries iCloud photo libraries, then downloads and names selected assets on local storage. Copy, sync, move, continuous watch, Live Photo/RAW handling, de-duplication, incremental selection, EXIF updates, and status reporting are additional product capabilities. Edges reflect the README and SOURCE INDEX references; unsampled modules are represented where documented, but their internal call paths are not inferred.
Main entry points: base.py Download runner · photos.py Photo libraries and assets · download.py Download selection · cli.py CLI options
Components 25
CLI and orchestration
- CLI options
src/icloudpd/cli.py - User config
src/icloudpd/config.py - Download runner
src/icloudpd/base.py
iCloud access
- Authentication and MFA
src/icloudpd/authentication.py - iCloud client
src/pyicloud_ipd/base.py - HTTP session
src/pyicloud_ipd/session.py - Photo libraries and assets
src/pyicloud_ipd/services/photos.py - API exceptions
src/pyicloud_ipd/exceptions.py
Asset processing
- Download selection
src/icloudpd/download.py - Asset versions
src/pyicloud_ipd/asset_version.py - Version sizes
src/pyicloud_ipd/version_size.py - Asset types
src/pyicloud_ipd/item_type.py - RAW and file policies
src/pyicloud_ipd/raw_policy.py - File matching
src/pyicloud_ipd/file_match.py - Live Photo naming
src/pyicloud_ipd/live_photo_mov_filename_policy.py
Local runtime
- Sync and deletion
src/icloudpd/autodelete.py - EXIF metadata
src/icloudpd/exif_datetime.py - Status reporting
src/icloudpd/status.py - JSON utilities
src/foundation/json.py - String utilities
src/foundation/string_utils.py - Log levels
src/icloudpd/log_level.py - Status server
src/icloudpd/server/__init__.py
Other components
- CLI user
- Apple iCloud
- Local photo files
Connections 25
- CLI user → CLI options: sets options
- CLI options → Download runner: starts
src/icloudpd/cli.py - CLI options → User config: configures
src/icloudpd/cli.py - Download runner → Authentication and MFA: authenticates
src/icloudpd/base.py - Authentication and MFA → iCloud client: logs in
src/icloudpd/authentication.py - iCloud client → HTTP session: creates
src/pyicloud_ipd/base.py - HTTP session → Apple iCloud: sends requests
src/pyicloud_ipd/session.py - iCloud client → Photo libraries and assets: provides library
src/pyicloud_ipd/base.py - Download runner → Download selection: runs downloads
src/icloudpd/base.py - Download selection → Photo libraries and assets: selects assets
src/icloudpd/download.py - Download selection → Asset versions: uses versions
src/icloudpd/download.py - Asset versions → Version sizes: uses sizes
src/pyicloud_ipd/asset_version.py - Photo libraries and assets → Asset types: classifies assets
src/pyicloud_ipd/services/photos.py - Photo libraries and assets → RAW and file policies: applies policy
src/pyicloud_ipd/services/photos.py - Photo libraries and assets → Version sizes: uses sizes
src/pyicloud_ipd/services/photos.py - Download selection → API exceptions: handles errors
src/icloudpd/download.py - Download runner → Local photo files: writes downloads
src/icloudpd/base.py - Download runner → Sync and deletion: syncs removals
src/icloudpd/base.py - Download runner → EXIF metadata: updates EXIF
src/icloudpd/base.py - Download runner → Status reporting: updates status
src/icloudpd/base.py - Status server → Status reporting: reads status
src/icloudpd/server/__init__.py - Photo libraries and assets → File matching: matches files
src/pyicloud_ipd/services/photos.py - Photo libraries and assets → Live Photo naming: uses naming policy
src/pyicloud_ipd/services/photos.py - Download runner → String utilities: uses helpers
src/icloudpd/base.py - HTTP session → JSON utilities: uses JSON
src/pyicloud_ipd/session.py