CLI tool
RhetTbull/osxphotos avatar
RhetTbull/osxphotos

osxphotos: reads Apple's Photos database, and says which macOS it cannot read

Python app to work with pictures and associated metadata from Apple Photos on macOS. Also includes a package to provide programmatic access to the Photos library, pictures, and metadata.

4,018 stars178 forksPythonMIT

At a glance

What is it?
A Python tool and library for querying and exporting from Photos.app, working on Linux as well as macOS. It publishes a compatibility table down to macOS Sierra, and one honest exception: shared albums do not work on macOS 26.x.
Who is it for?
Take osxphotos if you need to script against a Photos library rather than open the app, particularly if the library lives on a Mac you do not want to sit in front of, since the query and export paths work on Linux. Check three things first.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 6 days ago.
What is it written in?
Mainly Python, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 21, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • RhetTbull/osxphotos4,018 ★ · +156
Star history
Repository2026-09-242026-11-21
RhetTbull/osxphotos3.9k4k

156 Stars in the last 58 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The compatibility table runs to eleven rows and one exception

The support statement is a table of macOS versions against Photos.app versions, and it is more useful than any prose would be. macOS 27.0 Golden Gate pairs with Photos 12.0, macOS 26.0 through 26.7 Tahoe with Photos 11.0, 15.x Sequoia with Photos 10.0, 14.x Sonoma with 9.0, 13.x Ventura with 8.0, 12.x Monterey with 7.0, Big Sur with 6.0, Catalina with 5.0, Mojave with 4.0, High Sierra with 3.0, and Sierra 10.12.6 with 2.0. Every row is marked as supported. Below the table, testing is stated as running from macOS Sierra 10.12.6 through macOS Sequoia 15.i7.2, on both x86 and Apple silicon. One limitation is called out separately and not buried: OSXPhotos cannot read shared albums on macOS 26.x. And the newest row gets a caveat as well, with limited testing done for macOS 26.0 Tahoe to ensure basic functionality works, since not all features have been tested and some may not work.

It reads the database, and the reader does not have to be the creator

The mechanism is direct database access rather than screen scraping or scripting the app, and the page is explicit about how portable that is. It reads Photos databases for any supported version on any supported macOS version, with the example given being that you can read a database created with Photos 5.0 on macOS 10.15 while running macOS 10.12, and vice versa. That decoupling between the database format version and the OS version is the fact that makes the tool useful off a Mac. What you get from the query side is the library database: file name, file path, and metadata such as keywords and tags, persons and faces, and albums. On the export side it handles both the original and the edited photo, which is the distinction most tools get wrong. It also works with iPhoto libraries, though the page notes some features are available only for Photos, and only iPhoto 9.6.1, the final release, has been tested.

Four install routes, and Linux has its own failure mode

The recommended installer is uv, and the sequence is four commands. Install uv with the curl pipe from its install script, then install the tool with `uv tool install --python 3.13 osxphotos`. Upgrading is `uv tool upgrade osxphotos`, and trying it without installing is `uv tool run` or the shorter `uvx`. The `--python` flag is not decoration: on older macOS you must name an older interpreter, and the page gives a concrete case where macOS 12.7 requires Python 3.11. Homebrew is a tap plus an install, pip is a plain install from PyPI, and MacPorts is a `sudo port install`. Linux has a documented failure mode: at least one of the Linux-specific Python packages normally installed there can break installation with pip or pipx, producing an InvalidVersion error on a version string ending in `-1022-generic`. The advice in that case is to use the uv route instead, which is why uv is listed first rather than pip.

The git clone is over 3GB, and the page gives you a way around it

Cloning the repository is the one operation with a real cost, and the page is upfront about the number. The git repo is very large, more than 3GB, because it contains multiple Photos libraries used for testing on different versions of macOS. The recommended path for users is the PyPI package, which does not include the test libraries, or a pre-built executable from the releases if you only want the command line tool and are not comfortable running Python on your Mac. For contributors there is a documented alternative that skips the test data:

bash
git clone --filter=blob:none --no-checkout --sparse https://github.com/RhetTbull/osxphotos.git
cd osxphotos
git sparse-checkout set --no-cone '/*' '!tests'
git checkout

The pattern here is worth copying for any project with binary fixtures: a partial clone with no checkout, a sparse-checkout rule that includes everything except the tests directory, then a checkout. The repository also ships a `uv.lock`, so a contributor environment is reproducible.

Linux gets query and export, but not the macOS-only CLI surface

The Linux story is a documented subset rather than a promise of parity. Tested platforms are Ubuntu Linux and macOS, with the note that many features are only available on macOS. On Linux, the macOS-specific features of the CLI will not be available, and specifically will not be shown in the help output, which is a deliberate interface decision rather than an oversight: the command tells you what it can do on the machine you are running it on. What does work on Linux is the export and query CLI commands along with the Python API, and that combination is the reason to care, since it means you can export photos from a Photos library on a Linux machine. The practical shape is that you copy or mount the library, run osxphotos on Linux to read and export from it, and never open Photos.app at all. Python support is declared as greater than or equal to 3.10 and up to 3.14.

Both READMEs, a separate API document, and twenty-odd example scripts

The repository has two readme files at the root, `README.md` and `README.rst`, plus `API_README.md` and `README_DEV.md`, which is a sign of a project with a distinct audience for each. The packaging file points at the reStructuredText one as the published readme, with content type `text/x-rst`. The examples directory is the interesting part for learning the API, and its file names are the documentation: adding finder tags, adding size to a caption, adding to an album, album ordering, sequence and sort order, counting photos, batch edits, captions derived from comments and from filenames, comparing albums, concurrent export, copying photo metadata, deleting empty albums, querying a database version, a custom sidecar in three templating flavours, and a date delta helper. Three sidecar templates is a detail worth noting, since custom sidecars are the usual way people want output their own tooling can read.

Editorial conclusion

Take osxphotos if you need to script against a Photos library rather than open the app, particularly if the library lives on a Mac you do not want to sit in front of, since the query and export paths work on Linux. Check three things first. Shared albums cannot be read on macOS 26.x, which is stated plainly, so if shared albums matter to you, that version combination is out. On macOS 26.0 Tahoe the testing is explicitly limited to basic functionality and some features may not work. And if you clone the repository to contribute rather than to install, expect it to be over 3GB because it carries several test libraries, or use the sparse checkout the page gives you to skip them.

Frequently asked questions

how to install osxphotos

The recommended route is uv: install uv with its curl script, then run `uv tool install --python 3.13 osxphotos`. Homebrew needs a tap of RhetTbull/osxphotos, pip installs from PyPI, and MacPorts uses `sudo port install osxphotos`.

how to use osxphotos

It queries the Photos library database for file names, paths, keywords and tags, persons and faces, and albums, and exports both original and edited photos. It works on macOS and on Linux, where the export and query commands and the Python API are available.

Which Python versions does osxphotos support?

Python greater than or equal to 3.10 and up to 3.14. The uv install instructions name 3.13, and on older macOS you may need an older one, with macOS 12.7 called out as requiring Python 3.11.

Can osxphotos read a Photos library on Linux?

Yes. The export and query CLI commands and the Python API work on Linux, so you can export photos from a Photos library on a Linux machine. Database versions are decoupled from macOS versions, and macOS-specific CLI features are simply hidden from the help output on Linux.

Why is the osxphotos git repository so large?

It is over 3GB because it contains multiple Photos libraries used for testing on different macOS versions. Users should install from PyPI, which excludes the test libraries, and contributors can use the documented sparse checkout that skips the tests directory.

Official sources

  1. Issues
  2. License: MIT
  3. README
  4. Releases
  5. RhetTbull/osxphotos on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/rhettbull-osxphotos.svg)](https://hysenlabs.com/projects/rhettbull-osxphotos)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/rhettbull-osxphotos.svg)](https://hysenlabs.com/projects/rhettbull-osxphotos)

Was this useful?