iCloud Photos sync stuck is one of those macOS problems that looks simple until you actually open Photos and find two, sometimes three, separate photo libraries eating up your storage. I ran into this on a Mac mini I set up for a client last spring, and what looked like a five-minute fix turned into an afternoon of digging through library files. So let’s walk through why this happens and how to actually clean it up.
Quick Answer
- Duplicate Photos libraries usually happen when Time Machine restores, migration assistant, or an external drive creates a second
.photoslibraryfile that macOS doesn’t merge automatically. - iCloud Photos sync gets stuck most often from a corrupted local database, a full iCloud storage plan, or a network interruption mid-upload.
- Check System Settings > Apple ID > iCloud > Photos first to confirm sync is actually enabled and not paused.
- Rebuilding the Photos library database (hold Option+Command while opening Photos) fixes sync-stuck issues more often than any other single step.
- Never delete a
.photoslibraryfile without confirming which one is your System Photo Library first — you can check this in Photos > Settings > General.
Why This Happens
There isn’t one single cause here, which is part of what makes it annoying to troubleshoot.
Multiple System Photo Libraries. macOS only treats one library as the “System Photo Library” that syncs with iCloud. If you’ve ever restored from a Time Machine backup, used Migration Assistant, or manually copied a .photoslibrary file from an old Mac, you can end up with a second library sitting on disk that Photos never designated as the synced one.
A corrupted Photos database. The Photos app stores a local database inside the library package, and it can get corrupted from a forced quit during an import, a crash mid-sync, or a drive that wasn’t ejected properly. Once that database is unhappy, sync just stalls without any clear error message.
iCloud storage is full. This one’s embarrassingly common. If your iCloud plan is maxed out, Photos will happily sit there “syncing” forever without actually telling you storage is the problem — it just quietly stops uploading new photos.
Network interruptions during large uploads. If you’ve got thousands of RAW photos or 4K videos, a big library sync is fragile. A dropped Wi-Fi connection, a sleeping Mac, or even switching networks mid-upload can leave the sync queue stuck in a weird half-finished state.
Optimize Mac Storage confusion. When this setting is on, Photos keeps smaller versions locally and full-res versions in iCloud. But if the local cache gets out of sync with what’s actually in iCloud, you’ll see photos that appear to sync forever because Photos is essentially confused about what it already has.
Duplicate Libraries vs Stuck Sync: What’s Actually Different
| Symptom | Duplicate Libraries | Stuck Sync |
|---|---|---|
| Storage impact | High — full copies of photos on disk | Low to moderate, mostly cache bloat |
| Fix complexity | Manual merge or delete required | Often resolves with database rebuild |
| iCloud involvement | Not necessarily | Always involved |
| Common trigger | Migration, Time Machine restore | Full iCloud storage, network drop |
Step-by-Step Fixes
Step 1: Identify Your System Photo Library
Open Photos, go to Settings > General, and check which library is listed as active. Then use Spotlight to search for “photoslibrary” and see how many show up. If you’ve got more than one, note their file paths and sizes before touching anything.
Step 2: Check iCloud Storage First
Go to System Settings > Apple ID > iCloud and look at your storage usage. If you’re at or near your limit, that’s very likely why sync is stuck — no amount of restarting Photos will fix a full storage plan. Free up space or upgrade the plan, then give it a few minutes.
Step 3: Confirm iCloud Photos Is Actually Enabled
System Settings > Apple ID > iCloud > Photos. Toggle it off, wait about ten seconds, then toggle it back on. This sounds too simple to work, but it resets the sync handshake and clears a surprising number of stuck states.
Step 4: Rebuild the Photos Library Database
Quit Photos completely. Hold Option+Command and reopen Photos — you’ll get a dialog offering to “Repair” or “Rebuild” the library. Repair is faster and less risky; Rebuild is more thorough but takes longer on large libraries.
Step 5: Merge or Remove Duplicate Libraries
For the non-system library, open it separately (Option+click Photos, then Open Library) and check what’s actually inside. If it’s just old duplicates of what’s already synced, you can safely delete the file. If it has unique photos, you’ll need to export those and reimport them into your System Photo Library instead of merging the files directly — Photos doesn’t have a native merge tool.
Step 6: Check Available Disk Space
Photos needs local free space to process sync operations, even when Optimize Mac Storage is on. If your Mac’s drive is nearly full, that alone can stall syncing indefinitely.
What Actually Worked For Me
On that client Mac mini I mentioned, I first assumed it was a network issue since the sync spinner had been stuck at “1,247 items remaining” for two days straight. I restarted the router, restarted the Mac, signed out and back into iCloud — none of it moved the counter at all.
Turned out the real problem was a second .photoslibrary file left behind from a Time Machine restore months earlier, and macOS was somehow trying to reference photo IDs from that old library during sync, which caused the whole queue to choke. Not 100% sure why it referenced the wrong library — that’s not something Apple explains anywhere — but once I identified and removed the orphaned library, sync picked right back up within about twenty minutes.
That’s not the fix I expected to work, honestly. I’d been convinced it was a network problem the whole time.
Advanced Fixes and Edge Cases
Check Console.app for Photos-related errors. Filter by “photoanalysisd” or “cloudphotod” and reopen Photos while it’s running. You’ll often see specific sync failure codes that point at whether the issue is local database corruption or a server-side rejection.
Look at the photo count mismatch. Compare the item count shown in Photos on your Mac against the count shown on iCloud.com or on an iPhone signed into the same account. A big gap usually confirms sync is genuinely stuck rather than just slow.
Reset the System Photo Library designation. In rare cases, macOS loses track of which library is the System Photo Library entirely. You can reset this in Photos > Settings > General by selecting “Use as System Photo Library” on the correct file.
Check for external drive libraries. If your Photos library lives on an external SSD and that drive sleeps or disconnects, sync will stall silently without any real warning until you reconnect it.
Fixes That Sound Right But Rarely Help
Reinstalling macOS is the classic overkill move here, and it almost never fixes a Photos sync issue since the problem lives in the library file, not the OS install. Signing out of iCloud entirely and back in sometimes helps, but more often just resets the sync queue without addressing whatever caused the stall in the first place — the database rebuild in Step 4 does more real work than this does. And clearing Safari cache, which somehow shows up in a lot of forum threads about this, has literally nothing to do with Photos sync at all.
Prevention Tips
- Always eject external drives properly before disconnecting them if your Photos library lives on one.
- Keep at least 15-20% free space on your main drive so Photos has room to process sync operations.
- Don’t force quit Photos during an active import or sync — let it finish or pause it properly instead.
- Check iCloud storage usage every few months, especially if you shoot a lot of photos or 4K video.
- After a Time Machine restore or Migration Assistant transfer, immediately check for duplicate
.photoslibraryfiles before opening Photos for the first time.
FAQ
Why does my Photos sync say “Syncing” but never finish? Usually a full iCloud plan or a corrupted local database — check storage first, then try the database rebuild.
Can I merge two Photos libraries without losing anything? Not directly. Export photos from the non-system library and reimport them, since Photos has no built-in merge function.
Is it safe to delete a duplicate .photoslibrary file? Only after confirming it’s not your System Photo Library and doesn’t contain unique photos you haven’t backed up elsewhere.
Why do I have two photo libraries after a Time Machine restore? Time Machine restores often bring back an old library file that doesn’t automatically replace or merge with your current one.
Does turning off Optimize Mac Storage fix sync issues? Sometimes, though it also uses a lot more local disk space since it downloads full-resolution originals.
How long should a Photos library rebuild take? Depends on library size — a few minutes for small libraries, over an hour for libraries with tens of thousands of photos.
Will rebuilding my Photos library delete anything? No, it rebuilds the database and thumbnails, not your actual photos, though it’s smart to have a backup regardless.
Why does iCloud Photos show different item counts on my Mac and iPhone? That’s a sync-stuck indicator almost every time — one device hasn’t finished processing the queue yet.
Editor’s Opinion
this one’s frustrating because Apple gives you zero real error messages, just a spinning “syncing” that could mean five different things. if you’ve got duplicate libraries, check for them before you blame the network or iCloud itself — that’s the thing everyone skips. the database rebuild trick saved me more than once and it’s honestly underused for how well it works.
