Where Photos keeps your library, and what a Time Machine backup of it actually contains

#macos #photography #backup #mac

A Photos library on a Mac looks like one file in Finder, but it is a folder with several jobs inside. Knowing which part holds what explains a lot of "my album is gone" stories, and it tells you what a Time Machine backup really contains. Here is what we found while building a tool that reads these libraries, and how to check a backup by hand.

The library is a package

By default Photos keeps its library as Photos Library.photoslibrary in your Pictures folder. Control-click it in Finder and choose Show Package Contents (look, do not edit). On a current macOS library we see these folders:

database: the catalogue
originals: your original photo and video files
resources: smaller copies and other generated files, plus journals
private, scopes, internal, external

The split matters because the pieces fail differently.

What lives where

database/Photos.sqlite (with -wal and -shm files next to it while Photos runs) is a SQLite database. It knows your albums, folders, captions, keywords, favourites, which photos are hidden or in the trash, and where each file lives. Apple does not document its schema, and it changes between macOS versions, so treat anything you read from it as a snapshot of one version. If you ever open it yourself, work on a copy and never on the live library.

originals holds the actual files, in subfolders. Without the database the files are still there, but the albums and captions that tell you what they are are not.

resources/derivatives holds the smaller versions Photos makes for display. This matters with Optimize Mac Storage. On a real library of ours with that setting on, originals was empty and resources/derivatives/masters held only JPEGs: 7 of 7 photos had no original on the disk. For a video, the only local copy can be a still picture. If you copy such a library to another drive, you are copying thumbnails, and the full-size files stay in iCloud.

resources/journals is the least known part. These are Photos' own change logs, files ending in .plj: per kind of record there is a snapshot file with a full state, and a change file with what happened after it. They hold album titles, which photos are in which album, folders, captions, keywords and favourites. The format is not documented either; we worked it out by reading real libraries.

What Time Machine keeps

This is the surprising bit. tmutil can tell you what Time Machine skips:

tmutil isexcluded ~/Pictures/"Photos Library.photoslibrary"/database
tmutil isexcluded ~/Pictures/"Photos Library.photoslibrary"/resources/journals

On our Mac the first says Excluded and the second says Included. external is excluded too, while originals, resources, private, internal and scopes are included. We then made a real backup of a test library in a macOS 26.6 virtual machine and looked at the snapshot: no database folder, but the journals were there, complete, updated within seconds of a change.

So a Time Machine copy of your library has your original files and a change log, not the catalogue itself.

Restoring is less scary than it sounds

In the same VM we restored that library with tmutil restore and opened it in Photos. It rebuilt its database from the journals in under a minute, with the albums, folders, captions, keywords and favourites back, including changes made after the last snapshot. When we deliberately truncated the database of a copy, Photos' own repair failed in the one case we tried ("The library could not be opened"). Removing the database folder from that copy made Photos rebuild everything from the journals. This is one test on macOS 26, not a guarantee, but it is the reason we tell people: before paying anyone for anything, try restoring the library from Time Machine into a folder and opening it in Photos. People names are the part we could not confirm from journals.

Checking by hand what a backup has that your library lost

Say an album vanished after a move or a sign-out, and you want to know if an older copy still has it. Without extra tools:

Enter Time Machine, go to Pictures, pick a date before the problem, and restore Photos Library.photoslibrary to a folder on the Desktop. Never restore over your current library.
Quit Photos. Hold Option while opening Photos and choose the restored library.
Look for the album and compare. If you also want a number, count files in each package: find "<library>/originals" -type f ! -name '._*' | wc -l. Counts only compare fairly if both libraries had the same storage setting, because of the Optimize point above.

Opening a healthy library from an external drive works the same way, and Photos copes with libraries on APFS, HFS+ and exFAT in our tests (we copied with Photos quit).

A disclosure

We are a software company in Oslo, Norway, and we make AlbumRescue, a Mac app that reads these libraries without changing them: the scan, the lists and a comparison with another library are free, and it saves albums as plain folders with the original files and XMP sidecars. If the steps above solve your problem, you do not need it. There is more detail here: https://kayabyte-mac-licence.caner2u2.workers.dev/go/ar?s=devto-ar-library

(AI-assisted: drafted with an AI model, checked by us against our own tests and tool source.)

DEV Community