The command line for Apple Photos
osxphotos is a free, open-source command-line tool for exporting and querying Apple Photos libraries. Export originals and edited versions, preserve library metadata, and use templates to choose folders and filenames. A Python API lets you work with the library from your own scripts.
uv tool install osxphotosor pipx install osxphotos
Export, query, and automate
Combine metadata filters with export templates to choose which photos to export and how to organize them.
Export everything
Originals, edited versions, Live Photos, RAW+JPEG pairs, and every associated video — with the folder structure and filenames you choose.
Query library metadata
Keywords, albums, persons, places, dates, favorites, screenshots, missing files — combine dozens of options to select exactly the photos you want.
Sidecars & metadata
Export library metadata to XMP or JSON sidecars. With ExifTool installed, write keywords, captions, and other metadata into exported files.
Templating & scripting
A powerful template language and a Python API let you automate exports, build reports, and integrate osxphotos into your own workflows.
Runs on your terms
A fast, scriptable CLI that works on the command line, in cron jobs, or inside your scripts. No cloud, no lock-in.
Free & MIT-licensed
Completely open source and free forever. Trusted by photographers, archivists, and developers to move libraries safely.
A taste of what it does
Export every photo taken in 2024, organized into year/month folders, with sidecar metadata:
osxphotos export ~/Pictures/2024 \
--from-date 2024-01-01 --to-date 2024-12-31 \
--directory "{created.year}/{created.month}" \
--sidecar XMP --download-missingFree, forever
Star it on GitHub, read the docs, and take back control of your photo library.