Beyond the Ecosystem: How to Sync iCloud Photos to Linux via CLI

icloud-photos-downloader/icloud_photos_downloader

That’s why icloud-photos-downloader (often called icloudpd) is such a gem in the dev community. It gives you back control over your data.

From an engineering perspective, this isn't just a "downloader"—it's a tool for data sovereignty and automation. Here is why we love it

Automation & Cron Jobs
You can set this up on a home server (like a Raspberry Pi or a NAS) to run every night. No more manual "Select All" and "Download" in a browser.

Incremental Backups
It’s smart enough to check what you already have and only download new photos. This saves bandwidth and disk I/O.

Linux/Headless Support
Since Apple doesn't provide a native iCloud Photos client for Linux, this tool is the bridge we need for our server environments.

Metadata Preservation
It handles EXIF data and sidecar files properly, ensuring your photo's "birth certificate" (location, time, camera settings) stays intact.

Since it's a Python-based tool, the setup is straightforward. I recommend using a virtual environment to keep your global system clean.

Open your terminal and run

pip install icloudpd

To start a download, you'll point the tool to your Apple ID and a local folder.

icloudpd --directory ~/Pictures/iCloudBackup --username [email protected]

The first time you run it, the tool will prompt you for your password and the 6-digit 2FA code sent to your Apple devices.

Pro Tip
Use the --auth-only flag first to establish the session without starting a massive download immediately.

Authentication
Uses the pyicloud library to mimic a web login.

Session Storage
Saves a "cookie" (session token) locally so you don't have to log in every single time.

Syncing
Queries the iCloud API for a list of photo IDs and compares them against your local directory.

As an engineer, you probably want to "set it and forget it." Here is a simple Bash script you might use to automate the process

#!/bin/bash

# Configuration
DEST_DIR="/mnt/storage/photos"
APPLE_ID="[email protected]"

echo "Starting iCloud Sync at $(date)"

# Run icloudpd
# --skip-videos: if you only want photos
# --recent: only check the last 100 photos (much faster for daily runs)
icloudpd --directory "$DEST_DIR" \
         --username "$APPLE_ID" \
         --recent 100 \
         --auto-delete \
         --no-password-input

echo "Sync completed successfully!"

This tool is a fantastic way to bridge the gap between Apple's polished UI and our need for command-line efficiency.