steilerDev / icloud-photos-sync

One-way sync engine for the iCloud Photos Library into the native file system
https://icps.steiler.dev/
GNU General Public License v3.0
348 stars 9 forks source link
icloud icloud-api icloud-backup icloud-photos icloud-sync photos

icloud-photos-sync Logo

iCloud Photos Sync

GitHub release (latest by date) npm Docker Pulls


Get Started

CLI Reference


Test Coverage (Lines) Test Coverage (Functions)

Code of Conduct


Overview

This project provides a one-way sync engine for the iCloud Photos Library. The intention behind this project is to provide an easy way, to backup the full iCloud Photos Library to the native filesystem.

Currently, this can only be achieved, by having a Mac continuously run the Photos.app (with Keep originals enabled). With this method, the files cannot be easily viewed without the Photos.app.

This CLI Application offers the following high level functionality:

Continuously sync your complete remote iCloud Photos Library to your local file system efficiently

Efficient handling of local state

  • Each asset is only downloaded once and linked to its respective folders
  • No need track local state in database, since state is completely reflected in filesystem (through naming & linking)

Archiving of folders

  • All assets currently in the album will be persisted in the respective folder on the machine running icloud-photos-sync
  • Future syncs will ignore the folder (so those assets will not be changed/deleted)
  • If the remote album is moved, the archived folder will be moved to the same location
  • If the remote album is deleted, the archived folder will be put into a 'lost+found' type of folder
  • Optionally all photos from the archived folder can be deleted from the iCloud Photos Library, unless they are *Favorites* (reducing cloud storage needs)

Single purpose iCloud Photos application

  • No reliance on full fledged third-party libraries that provide access to iCloud
  • No configuration needed for continuous full backup
  • Quicker support of use-case specific needs

Documentation

A Get Started Guide can be found on GH Pages. Additional documentation and further resources - including my personal use case / workflow - are published there as well.

I am also trying to publish regular updates on the progress of this project in a development blog.

Limitations

As this application is using an undocumented public API, there are a couple of known limitations:

Please also check out open and known issues and existing feature requests for more information.

OS Support

OS Support Debian OS Support Ubuntu OS Support MacOS OS Support Windows

Contributing & Feedback

Please check the contributing guidelines to learn how to engage with this project.

Acknowledgments

Release Workflow

Nightly Release Status Beta Release Status Production Release Status

Monitoring Workflow

API Status