22-troubleshooting
Troubleshooting and FAQ
Frequently asked questions
Does Iris move or modify my photos?
No. Iris reads your files in place and stores everything it learns in its own database. Your originals are never copied, moved, renamed, or modified.
How long does initial processing take?
It depends on library size and the speed of your Mac:
- A few thousand photos: a few minutes
- Tens of thousands: an hour or two for the basics, several hours for ML
- Hundreds of thousands: up to a few days with all ML and transcription features enabled
You can use Iris while processing runs or leave it open in the background.
My photos don't have GPS data. Can I still use the Places features?
Iris won't auto‑associate non‑GPS photos with locations, but you can still create named locations. You won't see those photos on the Map view, but everything else (sidebar, search, chapters) works fine.
If you really want geographic data on a photo, you can edit it in another app that writes EXIF GPS, then re‑scan in Iris.
How do I mark a photo as a favorite?
Select it and press ⌘., or click the heart in the Inspector's Summary inspector tab's. Favorited items show up in the Favorites sidebar node.
Can I use Iris with multiple libraries in different locations?
Yes — that's the design. Add as many sources as you want, on any disk. Iris merges them in the All Items, date, person, place, and chapter views, so you don't have to choose between "one library" and "many folders."
Why doesn't Iris recognize a person I just named in new photos?
Face matching is probabilistic. Iris won't assign a face to a person unless it's reasonably confident. New people are particularly hard early on because Iris doesn't yet have many examples.
The fix: open the People tab on a few photos and assign people to unknown faces. After 5–10 confirmations, recognition usually becomes much more reliable. See People and face recognition.
What's the REST API server for?
It's how the iOS and Apple TV companion apps talk to your Mac. If you don't use either, you can leave it disabled in Settings → Server. See Companion apps and the local server.
How do I remove a source without losing my photos?
Right‑click the source in the sidebar and choose Delete. This removes the source from Iris's database — your actual files on disk are completely untouched.
My external drive is unplugged. What happens to those photos?
Their metadata and thumbnails stay in Iris. You can still browse thumbnails, see metadata, navigate by date, etc.
Iris is using a lot of CPU. What's happening?
Open the Pipeline Status window (⌘⇧1). If a stage is active — especially ML, transcription, or weather enrichment — that's the cause. The pipeline tries to stay polite (priorities are tuned to keep the UI responsive), but it does saturate cores during heavy work.
Options:
- Wait it out — the pipeline goes idle when it finishes.
- Disable one or more stages in Settings → Library to skip them.
Can I run Iris on more than one Mac sharing the same photos?
You can, but each Mac maintains its own database and processing state — Iris isn't designed to sync metadata between machines. The companion apps are a better way to browse the same library from multiple devices.
Getting help
If you're stuck:
When emailing support, mentioning your library size, your macOS version, and the contents of the Pipeline Status window helps a lot.