The ultimate bridge between iCloud Photos and your self-hosted Immich server.
One-time uploads. Zero duplicates. Complete control.
Features • Installation • Quick Start • Screenshots • Build
If you self-host Immich but your primary photo library lives in iCloud Photos, you need a reliable bridge. Immich-iCloud is that bridge — a native macOS app that reads your Photos library via PhotoKit and uploads every photo and video to your Immich server.
At its core, Immich-iCloud maintains a local SQLite ledger that tracks every upload by both asset ID and SHA-256 content fingerprint. Once an asset is recorded as uploaded, it will never be uploaded again — even if you:
- Delete it from Immich
- Reinstall the app
- Move to a new Mac (with ledger backup)
- Have duplicate files with different names
This isn't just a feature — it's the foundational promise of the entire application.
Dashboard — At-a-glance view of your sync status, server connection, and library statistics
View All Screenshots
Sync — Start, monitor, and control sync operations with real-time progress
History — View all-time statistics and detailed sync session history
Preview — Browse and explore your Photos library before syncing
Logs — Detailed event logging for troubleshooting and monitoring
Settings — Configure server, sync options, filters, and data management
| Feature | Description |
|---|---|
| One-Time Upload | Every asset uploads exactly once, tracked by local ID and SHA-256 fingerprint |
| Dry Run Mode | Simulate syncs without uploading — see exactly what would happen first |
| Checkpoint & Resume | Interrupted syncs save progress automatically; resume from where you left off |
| Concurrent Uploads | Upload 1-5 assets simultaneously for faster syncs |
| Exponential Backoff | Failed uploads retry with intelligent delays (1s → 2s → 4s... up to 30s) |
| Feature | Description |
|---|---|
| Start Date Filter | Only sync assets created after a specific date |
| Media Type Filter | Sync photos only, videos only, or both |
| Favorites Only | Restrict sync to your favorite assets |
| Album Filtering | Include specific albums, exclude albums, or sync from a single album |
| Shared Albums | Support for iCloud Shared Albums |
Choose exactly which assets to sync with the Selective Sync feature:
- Browse your library with thumbnail previews
- Select individual assets or entire groups
- Persist selections across app restarts
- Perfect for curated uploads
Create and manage albums on your Immich server:
- Map local albums to Immich albums
- Auto-create albums on Immich when syncing
- Support for Smart Albums and Shared Albums
- Sync album membership along with assets
Keep your ledger and Immich server in sync:
- Orphaned Assets — Find assets on Immich not in your ledger
- Missing Assets — Detect ledger entries deleted from Immich
- Checksum Mismatches — Identify content differences between local and server
- Batch delete orphaned assets directly from the app
Handle sync conflicts intelligently:
- Automatic conflict detection during reconciliation
- Review conflicts with detailed comparison views
- Multiple resolution strategies (keep local, keep server, skip)
- Track resolved vs. unresolved conflicts
| Feature | Description |
|---|---|
| Scheduled Sync | Auto-sync at configurable intervals (15 min to 24 hours) |
| Wake Sync | Automatically syncs when your Mac wakes from sleep |
| Launch Sync | Syncs on app launch with network reconnection delay |
| Pause/Resume | Temporarily pause scheduling without disabling it |
| Feature | Description |
|---|---|
| Custom Location | Store your database in Dropbox, iCloud Drive, or any folder |
| Multi-Mac Support | Share ledger across Macs via cloud-synced folders |
| Automatic Snapshots | Hourly backups with smart retention (2 hourly + 1 daily) |
| Snapshot Restore | Roll back to any snapshot with one click |
| WAL Checkpoint | Database integrity ensured on app quit for cloud sync safety |
- SwiftUI Interface — Modern, native look with full dark mode support
- Menu Bar Icon — Quick-glance sync status (idle, syncing, error)
- Dock Badge — Live upload count during sync
- Notifications — Alerts on sync complete or failure
- Keyboard Shortcuts — Full keyboard navigation (Cmd+1-6, Cmd+Shift+S, Cmd+?)
- Help Guide — Comprehensive 14-section guide with search and troubleshooting
| Feature | Description |
|---|---|
| Keychain Storage | API keys stored securely in macOS Keychain |
| HTTPS Only | All communication via encrypted connections |
| Zero Telemetry | No data sent anywhere except your Immich server |
| Local Ledger | All sync state stored locally — you own your data |
- Go to Releases
- Download
Immich-iCloud-2.1.0.dmg - Open the DMG and drag Immich-iCloud to Applications
- Launch from Applications (or Spotlight)
This app is not signed with an Apple Developer certificate. When you first open it, macOS Gatekeeper will display an error saying the app is "damaged" or "can't be opened." This is normal and expected.
To fix this (one-time setup):
- Open System Settings → Privacy & Security
- Scroll down to the Security section
- You'll see a message about "Immich-iCloud" being blocked
- Click Open Anyway
- Confirm by clicking Open in the dialog
The app will open normally after this one-time step.
- macOS 14.0 (Sonoma) or later
- A running Immich server (v1.90+)
- An Immich API key (how to generate)
- Launch the app — The onboarding wizard guides you through setup
- Connect to Immich — Enter your server URL and API key
- Grant Photos access — Allow access to your Photos library when prompted
- Dry Run first — Enabled by default; preview what would sync
- Sync for real — Disable Dry Run and start uploading
Tip: Use
Cmd+?anytime to open the comprehensive Help Guide.
The ledger is the heart of Immich-iCloud's safety model:
| Guarantee | Description |
|---|---|
| Upload Once | Once marked uploaded, an asset is permanently recorded |
| Fingerprint Dedup | SHA-256 hashing catches duplicate content across different files |
| Authoritative Ledger | The ledger — not Immich — determines upload status |
| Failure Safe | Failed uploads never overwrite successful records |
| Lookup Failure = Skip | If ledger lookup fails, the asset is skipped (never risk duplicates) |
| Shortcut | Action |
|---|---|
Cmd+1 – Cmd+6 |
Navigate between main tabs |
Cmd+Shift+S |
Start Sync |
Cmd+. |
Cancel Sync |
Cmd+R |
Refresh current view |
Cmd+? |
Open Help Guide |
Esc |
Close sheets/dialogs |
- Old Mac: Settings → Data Management → Export Ledger + Settings
- Transfer the
.immich-icloud-backupfile to your new Mac - New Mac: Settings → Data Management → Import Ledger + Settings
- Re-enter your API key (keys stay in Keychain, never exported)
- Settings → Database Location → Set Custom Location
- Choose a cloud-synced folder (Dropbox, iCloud Drive, OneDrive)
- Restart the app
- On other Macs, point to the same folder
Important: Don't run the app on multiple Macs simultaneously with a shared database.
- Xcode 16.0+
- XcodeGen —
brew install xcodegen
# Clone the repository
git clone https://github.com/bytePatrol/Immich-iCloud.git
cd Immich-iCloud
# Generate Xcode project
xcodegen generate
# Build
xcodebuild -project Immich-iCloud.xcodeproj -scheme Immich-iCloud -configuration Release build
# Run tests (52 tests)
xcodebuild -project Immich-iCloud.xcodeproj -scheme Immich-iCloud test./Scripts/build_dmg.sh| Layer | Technology |
|---|---|
| UI | SwiftUI + NavigationSplitView, @Observable (macOS 14+) |
| State | AppState singleton via .environment() |
| Database | GRDB + SQLite (WAL mode) |
| Photos | PhotoKit (PHAsset, PHAssetResource) |
| Networking | URLSession with multipart uploads |
| Security | macOS Keychain via Security framework |
| Concurrency | Swift async/await + TaskGroup |
| Updates | GitHub Releases API |
Immich-iCloud/
├── App/ # Entry point, AppDelegate, MenuBar, Commands
├── Core/ # AppConfig, FilterConfig, Models
├── Database/ # GRDB ledger, migrations, snapshots
├── Services/ # ImmichClient, PhotoKit, Keychain
├── Sync/ # SyncEngine, Scheduler, Retry, Checkpoint
├── UI/ # All SwiftUI views
│ ├── Components/ # Reusable UI components
│ └── Onboarding/ # Setup wizard
└── Utilities/ # Logger, Errors
Immich-iCloudTests/ # 52 unit tests
Scripts/ # Build and release scripts
Contributions are welcome! Please feel free to submit issues and pull requests.
MIT License. See LICENSE for details.
Made with care for the Immich community.