How iCloud Photos Sync works

This page explains what iCloud Photos Sync does behind the scenes: how it recognises photos you already have, how it repairs damaged ones, and how Apple edits, Live Photos, RAW files, albums and details come across. To connect an account and run a sync, start with Import from iCloud Photos.

Background imports

Everything runs on your server. Once you start a sync, you can close the browser or shut your computer down; the server keeps going and picks up where it left off after a restart. A sync runs again automatically on the interval you set (24 hours by default), and you can follow it in Activity like any other background job.

Each file is downloaded into a private staging folder on the server, checked, and only then added to your library. The staging budget you set for the connection limits how much space downloads in progress and recovery copies can use at once. When the budget is full, downloads wait until space frees up.

Recognising photos you already have

The sync compares file contents, not names. A renamed file can still be the same photo, and two files with the same name aren’t assumed to match. Sometimes a photo has to be downloaded once before Frameleaf can tell it’s an exact duplicate.

What Frameleaf already has	What the sync does
The same photo, and the file is healthy	Reuses it instead of importing another copy.
The same photo, but the file is missing, damaged, unreadable or offline	Downloads and checks the original, then repairs the existing photo.
Nothing matching	Imports a new photo.
The same photo, in your trash	Leaves it in the trash. The sync never restores something you deleted.
A matching file in an external library	Imports its own managed copy, so you keep it if the drive goes away. It never overwrites the external file.
An uncertain match, an unsupported file, or conflicting privacy or stack choices	Lists it for review rather than claiming success.

Same-asset recovery

Recovery repairs the photo you already have instead of adding a new one. The photo keeps its ID, so its albums and everything else attached to it stay in place.

A checksum stored in the database isn’t enough on its own: the sync checks the file on disk too. A photo imported months ago is fetched again if its Frameleaf copy later goes missing or gets damaged.
The downloaded copy has to pass validation before it counts. A failed check is never reported as a repair.
If only the movie half of a Live Photo is missing or damaged, the sync can recover just that part and leave the healthy still alone.
Repairs show as Missing original restored from iCloud or Damaged original restored from iCloud in the results, and administrators can see them as resolved items in Library Care.
Verified recovery copies that can’t be used yet stay in staging and keep counting towards the budget. They’re never deleted automatically.

Apple edits and stacks

With Edited versions turned on, every available Apple-edited photo or video becomes its own item in Frameleaf, grouped with its original in a stack. Open the stack to see every version and get to the original.

For example, you crop a photo on your iPhone. In Frameleaf, the original and the cropped version sit together in one stack. Edit it again later and another version joins the stack.

Which version shows. The latest Apple edit can become the one shown on your timeline, unless you’ve picked a different stack cover yourself or edited the photo in Frameleaf. Your choice wins, and the item is listed as Stack changed here · your stack was kept.
Reverting in Apple. Reverting to the original in Photos removes the edit as the preferred version. It doesn’t delete your original, older imported versions or anything you edited in Frameleaf.
What’s imported. Apple’s finished picture or video, not its adjustment settings. You can’t carry on editing Apple’s sliders in Frameleaf, but you can edit the photo in Frameleaf like any other.
Shared originals. Separate Apple photos with identical original files keep their own edits, even though they may share one original in Frameleaf.
Version limit. Up to 20 edit versions are kept per photo. A newer version beyond that is listed for review and the existing ones are kept. Choosing Retry again doesn’t get round the limit, so check the versions before removing anything.

Live Photo pairing

A Live Photo is a still image, such as a JPEG or HEIC, and a short movie. The sync uses Apple’s own identifiers to link the two, so they arrive as one Live Photo, with the movie as its motion part rather than a separate timeline item.

If a pair is ambiguous, it’s listed as Ambiguous Live Photo pair. Select Review to check it in Utilities, then Live Photo pairing, where you can also rejoin photos and movies that were imported separately by other means.

RAW and original files

Original files and RAW alternatives are kept as their own files. A JPEG preview is never used in place of an original HEIC or RAW file. If Frameleaf can’t decode a file, it’s listed for review.

Albums

Album names, nesting and memberships come across where Apple provides reliable information.
Albums keep their identity when you rename them in Apple, and two albums with the same name stay separate.
Each connection keeps its own album organisation.
Photos you already had, and photos that were repaired, join their iCloud albums without being imported again.
When the sync has a complete list from iCloud, it can remove a membership it added itself. It never removes a membership you added in Frameleaf, and never deletes your own albums.
Deleting an album in iCloud doesn’t delete its photos from Frameleaf.

Favourites, hidden photos and dates

Favourites, hidden status and capture dates are kept in step where Apple’s information is reliable.

Your changes in Frameleaf win. Locked details and changes you’ve made aren’t overwritten, and the item is listed as Changed both here and in iCloud · your change was kept.
Missing information in iCloud never erases a value in Frameleaf.
On the first sync of a photo you already had, an iCloud favourite can turn on the favourite in Frameleaf, because Frameleaf can’t tell an earlier “not a favourite” choice from the default. After that, the sync remembers what it has seen.
Unhiding a photo in Apple doesn’t remove a privacy choice you made in Frameleaf.
Captions, locations and time zones from iCloud aren’t supported. Values already in Frameleaf, whether read from the file or typed by you, are kept.

iCloud Photos Sync and the iPhone app

The Frameleaf iPhone app can back up the same iCloud photos the sync imports. The server keeps track of which iCloud item each photo came from (its source identity), so the two never download the same photo twice.

Recording. The sync records the identity of everything it imports, reuses or repairs. Photos it imported before this was added are filled in by the nightly clean-up.
Coverage. The app checks whether one of your connections covers the iPhone’s library. It sends a sample of up to 200 items, and a connection counts as covering the library when its last complete read of iCloud holds at least 95% of 20 or more samples.
Lookup. For each photo, the app can ask whether the server already has it, whether the sync will bring it, or whether it’s outside the sync’s selection. When the sync covers a photo and imports edits, it also brings the edited versions, and the app never uploads its own copy of the edit.
Matching rules. A match only counts when the file contents agree, or when the file name, capture date, type and size all agree. A weaker match is reported but never acted on.
Taking turns. Before either side fetches an iCloud photo, it claims it, including the still, the Live Photo movie, the RAW file and the current edit. While one side holds the claim, the other waits.
Taking over. A photo a healthy connection covers is the sync’s to fetch. If the connection stops working, you can ask the app to back the photos up from the iPhone straight away, and it takes over on its own after 72 hours.
Privacy. Answers only ever cover your own connections and photos. Locked and hidden photos follow the same rules as the app’s backup status.

Your administrator can turn this matching off with FRAMELEAF_ICLOUD_IDENTITY_MATCHING=false. Then only photos with identical file contents are treated as the same.

Counting photos and files

A Live Photo is one photo but two files, and an edited photo or a RAW pair has extra files too. That’s why the number of items settled can be higher than the number of photos you see. Imported, matched, repaired and review counts describe different outcomes, so don’t add them together to get a total.

Limits

Limit	Value
Connections per account	20
Libraries per connection	100
Albums per connection	10,000 (larger inventories fail with a clear error)
Albums shown in the picker at once	200 (search to find others)
Edit versions kept per photo	20
Concurrent downloads per connection	1 to 4
Sync interval	1 to 8760 hours

Interrupted downloads restart from the beginning of that file; a run resumes its saved work, but a single file doesn’t resume part-way through. The sync doesn’t delete leftover transcoded videos or XMP sidecar files.

Not supported

Apple Shared Albums, sharing permissions and Smart Albums. iCloud Shared Photo Library is supported.
Text-message verification codes.
Edited Live Photo pairing, Apple’s adjustment rendering, and special slow-motion and HDR edit effects. Don’t expect these to reproduce every Apple effect.
Captions, locations and time zones from iCloud.