Homelab: Migrating from iCloud to Immich

From iCloud Photo Library to Total Control Link to heading

With Immich configured and secure remote access working, it’s time to tackle the most important migration: transferring the entire photo library from iCloud to our self-hosted server. A decision that means abandoning iCloud’s convenience for complete control over our digital memories.

The process is not trivial: 50GB of photos on iCloud often transforms into 100GB of original data on local disk, including Live Photos, videos and metadata. The challenge is preserving albums, shared photos and ensuring a smooth transition for all devices.

Migration Options: Which to Choose? Link to heading

Recommended Method: Direct Immich CLI Link to heading

Direct CLI advantages:

• Maintains album structure automatically
• Includes shared photos (if downloaded locally)
• Single command for entire library
• Automatic resume in case of interruption
• No additional disk space required

Alternatives: Third-Party Tools Link to heading

For those preferring to completely bypass Apple’s Photos app:

iCloudPD - Direct iCloud Download:

# Install iCloudPD
pip3 install icloudpd

# Direct download from iCloud (bypass Photos app)
icloudpd --username [email protected] --password --directory ~/icloud_photos

iCloudPD advantages:

• Direct cloud download (not from Mac)
• Apple privacy bypass (no local control)
• Maintains original iCloud structure
• Automatic resume for interruptions

Disadvantages:

• Doesn’t maintain albums (only year/month structure)
• Requires direct iCloud credentials
• Possible rate limiting from Apple

Not Recommended Method: Manual Export Link to heading

Export via “Export Unmodified Originals” from Photos app:

Immich CLI Setup Link to heading

Installation and Configuration Link to heading

# On Mac, install Node.js if needed
brew install node

# Verify Immich CLI (without global installation)
npx @immich/cli --version

API Key Creation Link to heading

Before using CLI, you need to generate an API key from the web interface:

1. Access Immich: http://192.168.1.XXX:2283
2. Settings → Account → API Keys
3. Create API Key
   • Name: Migration CLI
   • Permissions: All (full access for upload)
4. Copy the generated key (long alphanumeric string)

# Login to Immich server with API key
npx @immich/cli login http://192.168.1.XXX:2283 YOUR_API_KEY_HERE

Essential Preliminary Tests Link to heading

Before starting the complete migration, a fundamental command to verify compatibility and content:

Dry Run - Complete Simulation Link to heading

# Test WITHOUT actual upload - originals only
npx @immich/cli upload ~/Pictures/Photos\ Library.photoslibrary/originals/ \
  --dry-run \
  --recursive

This command reveals:

• Total number of photos/videos detected
• Presence of shared photos in local database
• Album structure available for import
• Any file access errors

Complete Migration Link to heading

Once the process is validated with dry-run:

# Complete upload of originals with Mac standby prevention
caffeinate -i bash -c "echo 'Upload started: $(date)'; \
npx @immich/cli upload ~/Pictures/Photos\ Library.photoslibrary/originals/ \
  --recursive; \
echo 'Upload completed at: $(date)'"

Parameters used:

• caffeinate -i: Prevents Mac standby during upload
• --recursive: Explores all library subfolders

Anti-Duplicates Strategy Link to heading

1. Complete upload from Mac → Immich (complete library)
2. Disable iCloud Photos on iPhone (Settings → [Name] → iCloud → Photos → OFF)
3. Install Immich app on iPhone and configure only new photo backup

iPhone Configuration Link to heading

After complete migration and iCloud deactivation, two possible scenarios:

Scenario A - Complete Immich:

• Disable iCloud Photos on iPhone
• Install Immich iOS app
• Configure automatic sync to homelab server

Scenario B - Hybrid Approach:

• Keep iCloud active for new photos
• Use Immich as historical archive
• Periodic manual synchronization

Shared Photos Link to heading

Photos in shared libraries of other users might not be accessible if:

• Owner has limited download permissions
• You don’t have full access to shared library
• Apple blocks export of non-proprietary content

Backup and Security Link to heading

Before proceeding:

• Complete Mac backup (Time Machine)
• Verify available space on Immich (you’ll need more than iCloud space, in my case double)
• Test restore of some photos from Immich

Conclusions Link to heading

Migration from iCloud to Immich represents a significant step towards digital sovereignty. Using CLI directly from Photos Library ensures preservation of albums and structures, eliminating the complexity of manual export.

The process, once validated with preliminary tests, reduces to a single command that transfers years of photographic memories from Apple cloud to direct control of our homelab.

With Immich configured and migration completed, the homelab now manages two of the three personal digital pillars: photos and music. The third pillar - document management - represents perhaps the most complex challenge: transforming piles of papers and scattered PDFs into an intelligent and searchable archive.

→ Continue with: Homelab: Paperless-NGX and Document Management - Automatic OCR and intelligent classification for physical and digital documents.