osxphotos: Exporting and Querying Apple Photos Libraries from the Command Line

The problem osxphotos solves for Photos.app users

Apple Photos keeps its library in a database that the app itself does not expose for scripting. There is no supported command line interface to ask which photos have a given keyword, which album a photo belongs to, or which files are the edited versions. osxphotos fills that gap. The README describes it as providing "the ability to interact with and query Apple's Photos.app library on macOS and Linux", covering file name, file path, keywords, persons and faces, and albums, plus export of both original and edited photos. It also reads iPhoto libraries, though the README notes some features are available only for Photos. The audience is therefore people who already keep their photos in Photos.app and want to move metadata or files out of it in bulk: archivists, photographers migrating to another tool, and developers who want a Python object model over the library rather than a one-off export.

How osxphotos reads a Photos library

The tool works on the library database rather than driving the Photos.app interface. That is why it can run on Linux: the README states the export and query CLI commands and the Python API work there, which lets you export photos from a Photos library on a Linux machine. macOS-only features are simply absent from the help output on Linux. Version compatibility is handled by reading databases across releases; the README says the package will read Photos databases for any supported version on any supported macOS version, so a database created with Photos 5.0 on macOS 10.15 can be read on macOS 10.12 and the reverse. The supported table runs from Sierra (10.12.6, Photos 2.0) through Golden Gate (27.0, Photos 12.0), and the project says it is tested on x86 and Apple silicon. The Python API is the second half of the product: the same library that backs the CLI is importable, and the repository's examples directory contains scripts for tasks such as counting photos, comparing albums, adding Finder tags and writing custom sidecar templates.

Installing osxphotos with uv, brew or pip

The README recommends uv as the installation route. After installing uv and running uv self update if you already had it, the tool installs into its own environment:

uv tool install --python 3.13 osxphotos

After that, typing osxphotos in Terminal should run the command. Python support is 3.10 through 3.14, and the README warns that older macOS releases may need an older interpreter, giving macOS 12.7 with python 3.11 as the example. If you want to try it without installing, the README offers uv tool run --python 3.13 osxphotos or the uvx equivalent. Homebrew users can tap and install instead:

brew tap RhetTbull/osxphotos
brew install osxphotos

pip and MacPorts are also documented, with python3 -m pip install osxphotos and sudo port install osxphotos respectively. On Linux, the README notes that a distribution python package can break a pip install with an InvalidVersion error, and that uv is the workaround. A first real use is to list what the library contains before exporting anything; the CLI and its subcommands are covered in the project's command line reference, and the tutorial in the README is the place to start for export syntax.

Where osxphotos stops working

The clearest limitation is stated plainly in the README: osxphotos cannot read shared albums on macOS 26.x. If your workflow depends on shared albums, that release is a dead end for this tool. macOS 26.0 / Tahoe also gets a qualified note: limited testing was done to ensure basic functionality works, not all features have been tested, and some may not work. That is a different posture from the fully checked rows in the support table. On Linux the macOS-specific CLI features are not merely untested; they are removed from the help output, so a script written on a Mac may not be portable. There is also a practical cost in working from the repository: the README states the git repo is very large, over 3GB, because it carries multiple Photos libraries used for testing, and it recommends installing from PyPI instead if you only want the package. Finally, the tool's value depends on the Photos database being readable at all; it is not a replacement for Photos.app as an editor or organiser.

osxphotos compared with Apple's own export

The alternative most users reach for first is Photos.app's own File > Export, which writes files through a graphical dialog and keeps no record you can script against. The difference in approach is structural: the built-in export is interactive and one-shot, while osxphotos queries the database and can be re-run with the same arguments, filtered by keyword, album or person, and combined with a template system for output paths and sidecar files. That template system is a real differentiator, and the repository ships .mako examples for custom sidecar output in plain text, JSON and XMP. The trade-off is that you give up the visual review step. A GUI export lets you see a contact sheet before committing; osxphotos asks you to trust a query. For a one-time handoff of a few hundred photos, the built-in export is less work. For repeated, filtered or metadata-heavy exports, the scripted route is the only one that scales.

Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-09-23, the same day as the v0.77.1 release. Recent releases include v0.77.0 on 2026-09-20 and v0.76.1 on 2026-06-14, whose release note reads "Fix mcOS 27 beta support". That cadence suggests active work, but it also means the surface moves: each new macOS and Photos.app version is a compatibility event, and the support table is the artefact to check before upgrading your Mac. The licence is MIT, declared in pyproject.toml as an SPDX expression with an explicit license-files entry, and the project deliberately omits the legacy OSI classifier because setuptools 77 or later rejects using both. MIT is permissive, so redistribution and commercial use are broadly allowed, but this is not legal advice and the LICENSE file is the authority. Upgrading is cheap once installed: uv tool upgrade osxphotos, or python3 -m pip install --upgrade osxphotos for pip installs. The real upgrade cost is not the command but the re-verification of your export scripts against a new Photos.app database version.

Editorial conclusion

Adopt osxphotos if you need scripted exports, metadata queries or a Python API over a Photos library and you are comfortable reading its command line reference. Do not adopt it if you need a GUI, if you expect shared albums to work on macOS 26, or if you cannot run Python 3.10 through 3.14. Before committing, verify that your macOS and Photos.app version appear in the supported table, that your library is not a shared album, and that a test export of a small album produces the sidecar files you expect.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. RhetTbull/osxphotos on GitHub