Exporting My Photo Library from Apple Photos

What are the most important files you have? Photos. Photos of loved ones, family, friends, times past and places travelled. So it’s worth making sure they’re safe and easy to search.

This is how I exported 15 years worth of photos and their metadata from Apple Photos. If that’s what you want to do, and you’ve managed to wade through the useless search results round the very generic terms “Apple”, “Photos” and “Export”, and found this, then hopefully this will be of some use to you. You probably want to skip straight to the Tools section.

When I discovered that I needed to use my backups in earnest , I sadly discovered that the biggest weak point was probably also the most important.

Photos are some of your most important files to back up because the ones you have are unique, and few people are likely to have a copy if you loose yours. Other important documents you can get back, with time, money and effort; even things like birth certificates and other legal documents, but not your photos.

To manage my photos I started using iPhoto in 2006, and then its successor Photos. It’s not a huge collection, but at about 60 gigabytes, it’s about half my files by disk space. Generally both applications were OK¹, and had the advantage of being able to add metadata by grouping photos into albums or adding keywords. For photos metadata is very important, otherwise any large collection is almost unusable. You want to be able to sort and filter to find what you want, often by date, but also by event, location or people in the picture. Without this, it’s very hard to find anything, quickly anyway.

This information is kept in a database within Photos, and that’s there the problem lies. If you want the photo, plus the metatdata, you’re stuck with using Photos. If you don’t have another computer with that software, like me, you can extract the .jpg, but not these extra details.

That is where the weakness lies. If the database gets corrupted, deleted, or isn’t readable, all this extra information is lost - Photos doesn’t write it back into the photo file’s EXIF or IPTC metadata, so the photo is not a complete stand-alone item.

There is also no good way to export this information natively in Photos. Yes, you can export a particular album into a folder (of the same name), but if the photo exists in multiple albums with various attributes, that information doesn’t get exported at the same time.

And that’s what I want, to have my photo collection managed in an easy to use interface, but with all the extra metadata safely written back into each photo, so at any time, the photo is complete; both the actual picture, and its metadata in one place. This also makes it naturally system independent, because if the application making these changes writes them into the photo, there’s no worry about having to read a database written only for one specific application.

Tools

Most of the work is done with the OSX Photos application. It’s a python application you can use to export the data, or interact with the Photos database programatically. I only used it for the former, therefor I didn’t need to worry about setting up the correct python environment, you can just download and run a pre-built executable release .

This only works on a Mac, so if you have a photo library, but no access to a Mac, you’ll need to look for another solution, or borrow a Mac.

In addition, to write the metadata into the files, I needed to install ExifTool .

Steps

OSX Photos itself is well documented, and has good examples .

In my case I wanted to export the photos into folders sorted by date, and write the extra information I’d added over the years, such as tagged people, keywords, albums or the folder(s) the photos were in, into the metadata on the photo itself.

In the end I settled on the following command:

./osxphotos export --db "/Users/user/Pictures/Photos Library.photoslibrary" \
--export-by-date \
--from-date 2020-01-01 \
--to-date 2021-01-01 \
--exiftool \
--album-keyword \
--person-keyword \
--keyword-template "{folder_album(_)[_{album},]}" \
"/path/to/export/location/Photos Export"

The trailing backslash \ is just a way of adding a newline in Bash, which makes the commands easier to read, it doesn’t affect the options. The options specify:

• -db specify the .photolibrary file you want to export, you might have multiple ones. If you leave this option out is should fall back to use the default photo library set on your system.
• --export-by-date Exports photos into a directory structure in the format “yyyy/mm/dd”
• --from-date and --to-date I split my export up into blocks, as I had an issue with missing photos¹, detailed below . This meant if the export failed, only a part of it would fail and I wouldn’t have to start again. The dates are interpreted as timestamps to midnight. That means the --to-date doesn’t include any photos taken on that date. e.g. in my example only photos taken up to the start of the 1st January 2021 would be included in the export.
• --exif, --album-keyword and --person-keyword mean that ExifTool is used, to write any keywords that Photos has for a photo, including people, and any albums the photo sits in, into the metadata of the photo itself.
• --keyword-template "{folder_album(_)[_{album},]}" in addition to adding any albums that a photo sits in as a tag, it also adds the folder path, so you get all steps in a folder/album hierarchy. This (mis)uses OSX Photo’s templating systems to additionally substitute out the trailing album name, and the separating underscore, so that you are left with only the folder hierarchy as a separate tag. This works in my case as I only have one level of nesting, I never have folder1/folder2/album. It did mostly work, but in some cases would result in a photo have the tags of the album, the folders (as expected) but additionally the tag of “folder_album” as well. These were later easy to search for and remove though, as they were the only occurrences of underscores in any tags.

Missing Photos

One issue I encountered was that of missing photos. In the upgrade from iPhoto to Photos somehow it managed to lose some. It also managed to think it had lost some, when it hadn’t, which would involve me manually directing Photos to the photo it was missing inside its own photo collection when it asked.

Until this was fixed it would cause the export to crash. One way to identify some of the culprits was to use the --missing command:

./osxphotos query --db  "/Users/user/Pictures/Photos Library.photoslibrary" \
--from-date 2019-01-01 \
--to-date 2020-01-01 \
--missing

But that wouldn’t list all the offending photos. I ended up having to export smaller and smaller time periods to narrow down the photos that were causing the problem. When I’d found them I would have to fix it in Photos itself, either by, as above, manually locating the photo in the .photolibray bundle, or by deleting the photo from the collection.

New Home

Once the photos are exported you can just leave it there as an independent back-up, and carry on using Photos as you like.

I’ve decided not to do that, and instead use the DigiKam photo manager instead. It’s not quite as smooth and flashy as Photos, but it does write tags directly into the photos metadata, if you choose that option, and is more platform independent. I’m also hoping that it’s more reliable that iPhoto and Photos, which was able to, quietly and without warning, lose a number of my photos.