https://github.com/steilerdev/icloud-photos-sync

One-way sync engine for the iCloud Photos Library into the native file system
https://github.com/steilerdev/icloud-photos-sync

icloud icloud-api icloud-backup icloud-photos icloud-sync photos

Last synced: about 1 month ago
JSON representation

One-way sync engine for the iCloud Photos Library into the native file system

Host: GitHub
URL: https://github.com/steilerdev/icloud-photos-sync
Owner: steilerDev
License: gpl-3.0
Created: 2022-01-10T16:05:40.000Z (over 3 years ago)
Default Branch: main
Last Pushed: 2025-04-05T07:58:25.000Z (about 1 month ago)
Last Synced: 2025-04-07T04:02:34.964Z (about 1 month ago)
Topics: icloud, icloud-api, icloud-backup, icloud-photos, icloud-sync, photos
Language: TypeScript
Homepage: https://icps.steiler.dev/
Size: 7.78 MB
Stars: 368
Watchers: 8
Forks: 10
Open Issues: 9
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md

Awesome Lists containing this project

README

iCloud Photos Sync

## 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*.

*icloud-photos-sync is an independent project, and is not affiliated, endorsed, recommended by or otherwise affiliated with Apple Inc.*

This CLI Application offers the following high level functionality:

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

iCloud Shared Photo Library support

Support of MFA authentication through trusted devices, SMS and voice authentication - Security Key Support pending, please help out if you have this use case!

Enable autonomous operation, by caching of MFA trust token

Support of large libraries, through efficient diffing algorithm instead of full library pull

Full iCloud Photos Library backup with all important files in their original state and edits - Live Photos support pending

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 (optional)

Archiving an album will persist all assets in the respective folder in the local filesystem

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](https://icps.steiler.dev/get-started/). Additional documentation and further resources - including my [personal use case / workflow](https://icps.steiler.dev/dev/motivation/) - are published there as well.

## Limitations

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

- **iCloud Shared Photo Library**:
While this app is syncing all assets from the *Shared Photo Library*, unfortunately the API does not provide the location of shared assets within the user's folder hierarchy (when navigating to a folder on the WebUI while having *Shared Photo Library* enabled will yield an error). Until this functionality is available, *Shared Photo Library* assets will only be present in the `_Shared-Photos` folder and therefore cannot be archived.
- **FileType Support**:
The support of file types needs to be hardcoded by this application, since a full list is not available or retrievable. If you come across an `Unknown filetype descriptor` error, [please report it](https://github.com/steilerDev/icloud-photos-sync/issues/143), in order for the file type to be added to the application.

Please also check out [open and known issues](https://github.com/steilerDev/icloud-photos-sync/issues?q=is%3Aopen+is%3Aissue+label%3Aclass%28bug%29%2Cclass%28improvement%29%2C%22class%28known+issue%29%22) and [existing feature requests](https://github.com/steilerDev/icloud-photos-sync/issues?q=is%3Aopen+is%3Aissue+label%3Aclass%28feature%29+label%3Astatus%28open%29%2Cstatus%28wontfix%29%2Cstatus%28backlog%29%2C%22status%28help+needed%29%22%2C%22status%28in+progress%29%22%2Cstatus%28investigating%29%2Cstatus%28previewed%29+) for more information.

## OS Support

## Contributing & Feedback

Please check the [contributing guidelines](https://github.com/steilerDev/icloud-photos-sync/blob/main/CONTRIBUTING.md) to learn how to engage with this project.

## Acknowledgments

Special thanks to:
- [@foxt](https://foxt.dev/) for helping with reverse engineering the iCloud API ([GSA](https://github.com/steilerDev/icloud-photos-sync/issues/363) & [ADP](https://github.com/steilerDev/icloud-photos-sync/issues/202)). Check out [iCloud.js](https://github.com/foxt/icloud.js), in case you need to access other aspects of iCloud.
- [@konraddysput](https://github.com/konraddysput) for help on the Backtrace integration.
- [@timvahlbrock](https://github.com/timvahlbrock) for their interest in this project and contributions in getting it updated.
- All current and past sponsors of this project.

### Release Workflow