osxphotos export --download-missing --dry-run shows missing assets incorrectly on macOS Optimize Storage
Scripting an osxphotos export of an iCloud-synced album with --download-missing under macOS "Optimize Mac Storage", I ran it with --dry-run first to preview the scope. The summary looked like the export was broken:
Exporting 69 photos to /path/to/dest...
Processed: 69 photos, exported: 1, updated: 0, skipped: 0, updated EXIF data: 0, missing: 68, error: 0
Elapsed time: 0:00:00I read missing: 68 as "68 assets are unavailable" and exported: 1 as "only one file is actually retrievable" — i.e. that the album's originals had been evicted from local storage and a real run would come back nearly empty. Assumed the dry-run summary was a faithful preview of the real run, the way rsync --dry-run is. Nothing in the output says the 68 would be fetched, and --download-missing is already on the command line, so the counts look like they were produced with that flag honored. Also considered that album membership had not finished syncing, or that the export DB (.osxphotos_export.db) had gone stale and was mis-reporting state.
Trying to size the download properly instead, osxphotos query --album "<name>" --only-movies --json piped into json.load(sys.stdin) also failed:
File "/opt/homebrew/.../python3.14/json/decoder.py", line 363, in raw_decode
raise JSONDecodeError("Expecting value", s, err.value) from None
json.decoder.JSONDecodeError: Expecting value: line 1 column 1 (char 0)which I first read as the query returning nothing at all — suggesting the album filter or the --from-date bound had matched zero assets.
Dry run. --dry-run does not perform the iCloud download, so every asset whose original is not on local disk is counted as missing and excluded from exported. The dry-run summary is therefore not a preview of the real run's outcome — it is a preview of what would happen if nothing could be downloaded. missing: N in a dry run means "N assets are iCloud-only", not "N assets are unavailable".
Same command without --dry-run, same album, same flags, moments later:
Exporting 69 photos to /path/to/dest...
Processed: 69 photos, exported: 69, updated: 0, skipped: 0, updated EXIF data: 0, missing: 0, error: 0
Elapsed time: 0:01:20All 69 exported, missing: 0. The 68 iCloud-only originals were fetched by --download-missing (~2.1 GB in 82s). Note the dry run's Elapsed time: 0:00:00 versus 0:01:20 — because it downloads nothing, dry-run timing is useless for estimating the real export.
The JSONDecodeError. osxphotos query --json writes its library-processing progress log to stdout, ahead of the JSON payload:
Using last opened Photos library: ...
Processing database .../Photos.sqlite
Photos database version: 5001, 11.1.
...
[{"uuid": ...So the stream is not valid JSON from byte 0 and json.load() dies on line 1 column 1. Redirecting stderr (2>/dev/null) does not help — the preamble is on stdout. Slice from the first [:
raw = subprocess.run(cmd, capture_output=True, text=True).stdout
data = json.loads(raw[raw.find('['):])Sizing the fetch correctly. Don't gate on dry-run counts; query the library and sum real bytes:
total = sum(p.get('original_filesize') or 0 for p in data)
icloud_only = sum(1 for p in data if p.get('ismissing'))Treat Processed: N as the true scope and missing: as "how many need a network fetch".