PhotoPrism and JSON Sidecars From Google Takeout
How PhotoPrism uses sidecar files, what it reads from Google Takeout .json files and what it does not, and how to prepare a Takeout export for it.
You pointed PhotoPrism at your Google Takeout folder and it indexed everything, .json files included. Some photos have the right date, some have the wrong one, and the sidecars are sitting there as unrecognised files. You are not sure what PhotoPrism did with them.
What a sidecar is to PhotoPrism
PhotoPrism uses the word sidecar for two different things, which is where the confusion starts.
Its own sidecars. PhotoPrism writes YAML files into a sidecar folder, one per photo, holding the titles, labels, edits and dates you set inside PhotoPrism. These are its backup of your changes, so a rebuilt index does not lose them.
Sidecars it reads. When indexing, PhotoPrism looks for files with the same base name as a photo and a metadata extension. It reads XMP sidecars, which is the standard format Lightroom and Darktable write. It also has specific support for Google Photos .json sidecars, and it reads the taken date, location, title and description from them.
That last part is the useful bit. PhotoPrism was one of the first self-hosted apps to bother reading Google's format at all.
What Takeout .json gives it
A Google sidecar carries photoTakenTime, geoData with latitude and longitude, title, description, and a few flags such as favourite. PhotoPrism reads the taken time and the coordinates and uses them when the photo's own EXIF is missing or older. The full field list is in /blog/supplemental-metadata-json-explained.
So in principle a Takeout folder dropped into PhotoPrism's originals folder indexes with the right dates. In practice, several things get in the way.
Where it breaks
Name matching. Google truncates long filenames in the .json name and adds (1) suffixes in different places on the photo and the sidecar. IMG_20190714_110530(1).jpg may have a sidecar named IMG_20190714_110530.jpg(1).json. The newer .supplemental-metadata.json suffix gets cut short on long names too. PhotoPrism's matcher handles the common cases and misses the odd ones, and a missed match means the photo falls back to the file date.
Edited versions. Takeout ships photo.jpg and photo-edited.jpg with one sidecar between them. The edited copy often has no match. /blog/takeout-duplicate-photos-edited-versions covers the pairing.
Precedence. If a photo has an EXIF date, PhotoPrism trusts it over the sidecar. Usually right. Wrong when the EXIF date is a bogus one written by an editing app.
Only inside PhotoPrism. The dates PhotoPrism reads from the sidecar go into its database. The photo file still has no EXIF date. Copy that folder to a USB stick or open it in another app and the dates are wrong again.
The durable fix
Write the sidecar data into the files. Once DateTimeOriginal and the GPS tags are in the EXIF, PhotoPrism reads them first, name matching no longer matters, and the same files work in every other program. Then you can keep the .json files for reference or delete them.
exiftool can do it for the well-behaved files. The command and its limits are at /blog/exiftool-fix-google-takeout-dates. For the badly named ones you end up writing matching logic by hand.
Doing it with the app
Takeout JSON Metadata Fixer does the matching and the writing, and then produces a folder PhotoPrism can index without needing the .json files at all.
It reads every Takeout .json, including the truncated and (1)-shifted names and the .supplemental-metadata.json variant, matches each to its photo, and writes the date and GPS into the file's EXIF. Edited copies are handled. Filenames become readable and the folders follow a template such as Year/Month, or you can keep the album folders Google exported.
If you want sidecars beside the output anyway, turn on sidecar writing and the app puts a clean .json next to each file, with matching names, in the same shape Google uses. PhotoPrism reads them, and so does anything else that understands the format. The EXIF is still there as the primary copy.
Point PhotoPrism's originals folder at the result and index. Dates, places and order come out right the first time. Offline on macOS, Windows and Linux. Free for 500 photos, then $9.99 once.
Frequently asked questions
Should I delete the Takeout .json files after fixing the EXIF?
Once the data is in the files, the sidecars are redundant. Keep a zipped copy of the original export somewhere as a backup and delete them from the working library. PhotoPrism indexes faster without them.
Does PhotoPrism read Google's sidecars for videos?
Yes, the same way. The taken time is used for the video's date. Videos in Takeout often lack the date inside the file, so the sidecar matters more for them.
Will PhotoPrism re-read the EXIF after I fix the files?
Run a full re-index from the library page. PhotoPrism compares file changes and updates metadata for files that changed. If dates do not update, check that the file's modified time changed, since that is what triggers a re-read.
Can PhotoPrism write the dates back into my files?
PhotoPrism keeps edits in its own YAML sidecars and database. It does not modify your original files. That is a deliberate choice, and it means the fix has to happen before indexing if you want it inside the photos.