Skip to content

videre import

Brings a library in from somewhere else: a Google Takeout export, an Apple Photos or iPhoto library, or an Adobe Lightroom catalog. It works out what you pointed it at, finds the actual files, and reports what it found. It changes no file: videre scan reads a Takeout photo’s real date and place from its sidecar, and videre fix-dates sets that date as the file’s time.

Terminal window
videre import ~/Pictures # find whatever is in there
videre import ~/Takeout # a Google Takeout export
videre import ~/Pictures/Photos\ Library.photoslibrary
videre import # search the usual places
videre --library ~/Photos import ~/Takeout # import into a selected library

Import brings files into the library it is run in: the invocation directory, or the one named by --library <DIR>. The source path you pass is where the photos come from; the library is where their records go.

The bare path is the main form. You do not need to know whether you have a .photoslibrary, a .lrcat or a Takeout dump, and you do not need to know where inside it the files are kept.

Every source resolves file locations through the same ladder, stopping at the first step that works:

Step What it tries
1 The provider’s own catalog. Only when you pass --use-library-db, or for Lightroom, where there is no alternative
2 Known folder layouts: originals/, Masters/, Originals/, Google Photos/
3 Asks you, via --originals <dir>

The default never opens a provider database. Apple, in particular, is read purely from the filesystem, because Apple’s schema changes between macOS releases and its folder layout does not.

Each run reports which step succeeded, so you can see how your files were found:

Located 46,118 file(s) via originals/ (catalog not read).

Apple renamed that folder twice, so all three spellings are recognised: early iPhoto used Originals/, iPhoto 9 used Masters/, and Photos on Mojave and later uses lowercase originals/ with a hex fan-out.

If a vendor changes their structure in a version newer than your videre, you are not stuck. --originals overrides every step:

Terminal window
videre import --originals ~/somewhere/photos ~/Pictures/Odd.photoslibrary
Option Effect
--originals <dir> Where the files actually are. Overrides every detection step
--use-library-db Also read the provider’s catalog to locate files. Off by default
--allow-partial Proceed without prompting when an Apple library looks optimised
--dry-run Report only. Import changes no file either way
-y, --yes Skip the confirmation prompts (Apple and Lightroom)
--silent No per-file output. Errors always show
--json One JSON summary object on stdout
Terminal window
videre import ~/Takeout # see what the export holds
videre --library ~/Takeout scan # record it, dates and places from the sidecars
videre --library ~/Takeout fix-dates # set those dates as the files' times
videre dedupe trash # collapse the copies albums created

Import deliberately does not scan for you, keeping each command to one job. The order of import and scan does not matter: scan reads the sidecars itself, so a Takeout export dated correctly even if you never ran import.

Takeout puts each photo’s real capture date and place in a .json sidecar rather than in the file, so a photo with no EXIF date (WhatsApp and Viber images, screenshots, scans) carries the day you unpacked the export. videre scan reads those sidecars, so each such photo lands on the day it was taken; import reports how many sidecars it found and what they hold:

14143 matched a sidecar (97.7%)
14143 with a capture date and 10775 with a place; videre scan reads both

The sidecar names are the hard part: Google truncates them at around 46 characters, so photo.jpg.supplemental-metadata.json can arrive as photo.jpg.suppl.json or even photo.jpg.s.json. Import handles those, plus (1) duplicate counters and -edited versions.

Google Photos exports every photo you edited twice, IMG_1.jpg and IMG_1-edited.jpg. When the export has such pairs, import counts them and its closing hint adds the two commands that deal with them:

Next:
videre scan ~/Takeout/Google Photos
videre fix-dates # set 14143 file time(s) from their sidecar
videre dedupe review --kind creation # review 3763 photo(s) Google Photos made from another
videre dedupe trash --kind creation # keep the originals, trash the creations

--json reports the count as edited_pairs. See dedupe --kind creation.

Point it at whichever level you have: the folder you extracted into, the Takeout/ folder, or Google Photos/ itself all work.

It uses photoTakenTime, never creationTime. The second one is when the file was uploaded to Google, often years after the photo was taken, and using it is the most common way other tools get this wrong.

When a name is ambiguous, no date is applied. If a truncated name could belong to two sidecars, the file is left alone and counted separately. A wrong date is worse than a missing one.

A photo’s own EXIF date wins. The sidecar is used only for a photo whose file records no date, and for a place only when the file has none.

Reads originals/ (or Masters/, or Originals/) directly. Before starting it prints a short checklist, because two things about the library’s state matter more than anything videre can detect:

  1. Download Originals to this Mac. If “Optimise Mac Storage” is on, the files on disk are smaller stand-ins rather than your originals. This is the one worth getting right: once you delete the Apple library, whatever was only in iCloud is not coming back.
  2. Optionally empty Recently Deleted, since deleted photos are still on disk and will be imported. Harmless, as you can delete them again from videre, but it saves a pass.

As a safety net, import warns when the library’s median file size looks too small to be originals. That is a judgement about the library as a whole, not per file, because individual small files are perfectly normal.

It also detects a referenced library, where Photos links to files elsewhere rather than copying them in. There the answer is to point videre at your real folders instead.

If originals/ turns out to be completely empty, import stops and explains rather than reporting zero files. That state has two causes which are indistinguishable on disk, so both are offered: iCloud has evicted your originals, or the library is a referenced one. The first is checked in Photos > Settings > iCloud, the second in Photos > Settings > General. A referenced library needs no import at all; its files are ordinary photos, so videre scan is the whole answer.

Lightroom never owns your files: the catalog is a set of pointers to ordinary folders you chose. So import reads .lrcat to find out which folders, which is the one thing a filesystem scan cannot tell you.

The catalog is copied before reading, never opened in place, since Lightroom holds it open.

Root folders on drives that are not connected are reported as offline and skipped, not treated as missing files:

Catalog references 4 root folder(s):
/Users/you/Pictures/2024 online
/Volumes/Archive/Photos OFFLINE

Import changes no file. Earlier versions set file times from the sidecars themselves, in UTC, while fix-dates set them from EXIF in local time, so on a photo with both the two commands disagreed by hours and undid each other. Now fix-dates is the only command that changes a file’s time.

It reads other applications’ libraries, and only reads. Nothing is written back to a Photos library or a Lightroom catalog.

An ordinary folder of photos needs no import at all. If nothing importable is found, it says so and points you at videre scan, which is the right answer for a plain folder.