Import from iCloud Photos

iCloud Photos Sync imports your iCloud Photos library into your own Frameleaf account. Downloads run on your server, so they carry on after you close the browser, and the sync checks for new photos on a schedule you choose. You can import Apple’s edited versions alongside the originals, keep Live Photos together, and repair Frameleaf files that have gone missing or become damaged.

It’s a one-way import:

Nothing is ever written back to iCloud.
Deleting a photo in iCloud doesn’t delete it from Frameleaf. It’s listed as “Deleted in iCloud · kept here”.
No original already in Frameleaf is overwritten.
Disconnecting or removing a connection leaves your imported photos where they are.

This page walks you through connecting and running a sync. For how matching, repairs, Apple edits, Live Photos and albums work in detail, see How iCloud Photos Sync works. Administrators set the feature up with iCloud Photos Sync server setup.

Before you start

Your administrator has turned the feature on. If the page says iCloud Photos is unavailable, the server doesn’t have the iCloud bridge, its encryption key or private staging storage set up yet. Signing in can’t fix that; ask your administrator.
You open Frameleaf over HTTPS. Signing in to iCloud needs a secure connection to your server.
You have your Apple account password and a trusted Apple device to hand. Verification codes come from that device. Text-message (SMS) codes aren’t supported.
Access iCloud Data on the Web is turned on for your Apple account, on a trusted Apple device. If you use Advanced Data Protection, Apple may ask you to approve web access again when it expires.

Connect your account

Open Utilities, then iCloud Photos.
Select Add connection. Frameleaf creates a connection called “iCloud connection 1” (you can rename it later).
Select Connect account.
Enter your Apple account email and Password, then select Connect account.
If Apple asks for a code, enter the Six-digit verification code shown on your trusted device and select Verify connection.
If Apple asks for device approval instead, approve web access on your trusted device, then select Check device approval. Each check makes one request to Apple, so approve first and check once.

If the sign-in gets stuck, select Sign in again to start over.

Your password and code are sent once and never kept. Frameleaf stores an encrypted session instead, so you don’t have to sign in for every run. Too many sign-in attempts lock you out for 15 minutes.

Choose what to import

Your photo libraries appear under Photo libraries once the first sync has read the account. While the library is still being read, the page says so. Albums or photos missing from a partial list are never treated as removed.

Photo libraries. Your Personal library and any Shared library (iCloud Shared Photo Library) are listed. Choose at least one. Apple Shared Albums are a different thing and aren’t supported.
Source albums. Leave every album unselected to import all albums, and every photo outside an album, in the selected libraries. Or tick only the albums you want. Use Find albums to search by name: the list shows the first 200 matching albums, and albums you’ve already selected stay selected. Nested albums show their parent album’s name.
Include. Choose whether to import Edited versions and Hidden photos (see below).

Sync preferences

Setting	What it does	Default
Edited versions	Imports Apple’s finished edits as separate photos, stacked with the original.	On
Hidden photos	Imports photos from Apple’s Hidden album. They arrive in Locked and stay hidden until you unlock.	Off
Connection name	The name shown for this connection, up to 100 characters.	iCloud connection n
Check every (hours)	Time between scheduled syncs, from 1 to 8760 hours.	24
Concurrent downloads	Downloads at once for this connection, from 1 to 4. Your administrator may set a lower server-wide limit.	1
Staging budget (GiB)	Space reserved on the server for downloads in progress and recovery copies. This is separate from your storage quota.	20

Select Save sync preferences after any change. If you turned on Hidden photos, Frameleaf shows Review import access first; select Allow and save. Because hidden photos arrive Locked, saving asks you to unlock with your PIN, then brings you back with your choices filled in. Save once more to finish.

If you set a staging budget or concurrency above what your administrator allows, saving fails with a message asking you to lower it.

A photo that matches a file in one of your external libraries is still imported as its own copy in Frameleaf’s storage, so you keep it if that drive is disconnected.

Run and watch a sync

The connection card shows its status, such as Syncing, Paused, Waiting for iCloud or Needs attention. While a sync runs, Sync progress shows how many items are settled out of the total, and Open in Activity shows it alongside your other background work. When nothing is running, the card shows when the next scheduled sync is due.

Control	Use it to
Sync now	Start a sync with your saved preferences.
Pause / Resume	Stop after the item in progress, and carry on later without losing your place.
Cancel	Stop the current sync. Photos already imported are unchanged.
Retry	Try again the items that didn’t finish, once you’ve fixed the cause.
Rescan source	Check every item again against iCloud. Nothing is deleted and imported again.
Refresh	Reload the saved progress and results.

Counts survive closing the page and restarting the server. Downloads that are interrupted start that file again from the beginning.

Review the results

Reconciliation summarises what happened: imported, matched, review and skipped, plus repaired, failed and “deleted in iCloud and kept here” when there are any. Below it, recent results each have an Open link to the photo:

Result	Meaning
Imported	A new photo or video was added to your library.
Existing original matched	Frameleaf already had this exact file, so it was reused rather than copied.
Missing original restored from iCloud	Frameleaf’s copy had gone missing and was put back from iCloud.
Damaged original restored from iCloud	Frameleaf’s copy was damaged and was replaced with a verified copy from iCloud.

Items that need a decision are listed with the reason:

Reason	What it means
In your trash here · kept there	You trashed this photo in Frameleaf. The sync never restores it.
Deleted in iCloud · kept here	The photo is gone from iCloud but stays in Frameleaf.
Hidden in iCloud · include hidden photos to import it	Turn on Hidden photos to bring it in.
Matches a file in your external library	Check the match before deciding.
More than one possible match here · review before importing	Frameleaf won’t guess. Open the photo and check.
Ambiguous Live Photo pair	Select Review to check it in Live Photo pairing.
Too many edited versions kept for this photo	The limit of 20 edit versions per photo was reached.
Changed both here and in iCloud · your change was kept	Your Frameleaf change wins.
Stack changed here · your stack was kept	Your stack arrangement wins.
Storage quota reached	Free some space or ask for a larger quota, then retry.
Not a supported photo or video	The file can’t be imported.
Could not be imported · retry to try again	Fix the cause, then select Retry.

Administrators also see links to Resolved missing media and Resolved damaged media in Library Care after a repair.

Manage the connection

Select Review connection on the connection card to:

Check saved session, to see whether the stored Apple session still works.
Disconnect, to stop new imports and forget the saved Apple session. Photos already in Frameleaf stay.

To delete a connection entirely, disconnect it first, then open it again and select Remove connection. Imported photos stay. If some imports were still being written, reconnect to let them finish, then remove it.

You can keep up to 20 connections, for example one per Apple account. Switch between them with the Connection list.

Using the Frameleaf iPhone app at the same time

The Frameleaf iPhone app can back up the same photos the sync imports. The server records which iCloud item each photo came from, so the app and the sync never both upload the same photo. If your iCloud connection stops working, the app can take over: you can ask it to back the photos up from the iPhone straight away, and it takes over on its own after 72 hours. See How iCloud Photos Sync works for the details.

Troubleshooting

What you see	What to do
iCloud Photos is unavailable	Ask your administrator to finish server setup.
Signing in to iCloud needs a secure (HTTPS) connection	Open Frameleaf at its HTTPS address.
Apple is waiting for a verification code, or for device approval	Open the connection with Review connection and finish the step.
Apple needs you to sign in again	Your session expired. Connect the account again.
Too many sign-in attempts	Wait 15 minutes and try again.
iCloud asked us to slow down, or iCloud did not respond	Nothing to do. The sync waits and carries on by itself. Don’t add extra connections to get round it.
iCloud reset its change history	Nothing to do. The next sync reads the library again, and nothing is lost.
The staging budget is full	Raise Staging budget (GiB), or ask your administrator to free space on the server, then select Retry. Never empty the staging folder by hand.
The sync could not make progress for a day	Items are waiting for staging space or keep failing. Raise the staging budget, then retry.
Imported items could not be finished	Select Retry. If it keeps happening, ask your administrator to check the server’s queues and storage.
The server’s iCloud setup is incomplete	Ask your administrator to check the setup.

What isn’t supported

Apple Shared Albums, sharing permissions and Smart Albums.
Text-message verification codes.
Captions, locations and time zones from iCloud. Values already in Frameleaf are kept.
Edited Live Photo pairing, Apple’s adjustment settings, and special slow-motion and HDR edit effects.
More than 100 libraries or 10,000 albums per connection.