OSXPhotos

PyPI - Python Version

OSXPhotos provides the ability to interact with and query Apple's Photos.app library on macOS and Linux. You can query the Photos library database — for example, file name, file path, and metadata such as keywords/tags, persons/faces, albums, etc. You can also easily export both the original and edited photos. OSXPhotos also works with iPhoto libraries though some features are available only for Photos.

Supported operating systems
Installation
Documentation
Getting Help
Command Line Usage
Python API
Template System
Related Projects
Contributing
Known Bugs and Limitations
Implementation Notes
Acknowledgements

Supported operating systems

Tested on Ubuntu Linux and macOS. Many features are only available on macOS.

On Linux, macOS-specific features of the CLI will not be available (these will not be shown in the help output). The export and query CLI commands as well as the Python API will work on Linux which enables you to export photos from a Photos library on a Linux machine.

Tested on macOS Sierra (10.12.6) through macOS Sonoma (14.1). Tested on both x86 and Apple silicon (M1).

OSXPhotos has been minimally tested with macOS Sequoia (15 beta) but new beta versions may break osxphotos support. If you encounter problems with macOS 15.0, please open an issue.

macOS Version	macOS name	Photos.app version
15.0 beta	Sequoia	10.0 (beta support)
14.0 - 14.6	Sonoma	9.0 ✅
13.0 - 13.6	Ventura	8.0 ✅
12.0 - 12.7	Monterey	7.0 ✅
10.16, 11.0-11.7	Big Sur	6.0 ✅
10.15.1 - 10.15.7	Catalina	5.0 ✅
10.14.5, 10.14.6	Mojave	4.0 ✅
10.13.6	High Sierra	3.0 ✅
10.12.6	Sierra	2.0 ✅

Limited support is also provided for exporting photos and metadata from iPhoto libraries. Only iPhoto 9.6.1 (the final release) has been tested.

This package will read Photos databases for any supported version on any supported macOS version. E.g. you can read a database created with Photos 5.0 on MacOS 10.15 on a machine running macOS 10.12 and vice versa.

Requires python >= 3.9, <= 3.12. Reading iPhoto libraries requires python >= 3.10.

For macOS 15.0 / Sequoia developer preview, alpha support is provided (very preliminary, not guaranteed to work). Not all features of osxphotos have been tested and some features may not work. If you encounter issues, please open an issue on GitHub.

Installation

If you are new to python, I recommend you install osxphotos using pipx. See other options below. If installing on Linux, see instructions below.

Installation using pipx

If you aren't familiar with installing python applications, I recommend you install osxphotos with pipx. The easiest way to do this on a Mac is to use homebrew:

Open Terminal (search for Terminal in Spotlight or look in Applications/Utilities)
Install homebrew according to instructions at https://brew.sh/
Type the following into Terminal: brew install pipx
Ensure that pipx installed packages are accessible in your PATH by typing: pipx ensurepath
Then type this: pipx install osxphotos
Now you should be able to run osxphotos by typing: osxphotos

Once you've installed osxphotos with pipx, to upgrade to the latest version:

pipx upgrade osxphotos

[!NOTE] When installing other packages with homebrew, homebrew may update the version of Python installed which would then cause any app (including osxphotos) installed with pipx to fail. If this happens, the easiest fix is to reinstall osxphotos with:
pipx reinstall osxphotos
Alternatively, you can reinstall all apps installed with pipx with:
pipx reinstall-all

Installation using pip

You can also install directly from pypi:

python3 -m pip install osxphotos

Once you've installed osxphotos with pip, to upgrade to the latest version:

python3 -m pip install --upgrade osxphotos

Installation via MacPorts

If you use the MacPorts package manager on a Mac:

sudo port install osxphotos

Installation on Linux

At least one of the Linux-specific python packages normally installed on Linux may cause an error during installation with pip or pipx. If you encounter an error similar to: pip._vendor.packaging.version.InvalidVersion: Invalid version: '6.5.0-1022-generic, you should still be able to install osxphotos by creating and activating a virtual environment:

python3 -m venv .venv-osxphotos
source .venv-osxphotos/bin/activate
python3 -m pip install osxphotos

To use osxphotos you will need to ensure the venv is activated using source .venv-osxphotos/bin/activate.

You may name the virtual environment anything you want; .venv-osxphotos is used in this example to make it clear the virtual environment is used by osxphotos and to avoid conflict with other virtual environments which, by convention, are often named .venv or venv.

Installation from git repository

If you want to work on osxphotos code or contribute to the project, you can install from the git repository:

git clone https://github.com/RhetTbull/osxphotos.git
cd osxphotos

[!NOTE] The git repo for this project is very large (> 3GB) because it contains multiple Photos libraries used for testing on different versions of macOS.

If you just want to use the osxphotos package in your own code, I recommend you install the latest version from PyPI which does not include all the test libraries. If you just want to use the command line utility, you can download a pre-built executable of the latest release or you can install via pip which also installs the command line app. If you aren't comfortable with running python on your Mac, start with the pre-built executable or pipx as described above.

Alternatively, to clone the repository without the test data:
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

Next, install the required dependencies, and osxphotos itself. I recommend you create a virtual environment before installing osxphotos.

python3 -m pip install -r dev_requirements.txt
python3 -m pip install -r requirements.txt
python3 -m pip install -e .

Once you've installed osxphotos via the git repository, to upgrade to the latest version:

cd osxphotos
git pull
python3 -m pip install -e .

See also the developer notes in README_DEV.md.

Installing pre-built executable

You can also download a stand-alone pre-built executable--that doesn't require installing python--from the releases page. Look for the file with a name similar to osxphotos_MacOS_exe_darwin_x86_64_v0.63.5.zip. In this case v0.63.5 specifies version 0.63.5 and x86_64 specifies Intel x86 platform; you should download the latest version available. For Apple Silicon, there is an equivalent arm64 version of the executable. Unzip the file and put the included osxphotos binary in your system path. Currently, the binary is not notarized so you'll have to authorize the app to run in the System Preferences | Security & Privacy settings. If you don't know how to do this, I recommend using pipx as described above.

Documentation

See the documentation for more information on using osxphotos.

Getting Help

OSXPhotos is well documented. See the tutorial for a description of key features. The tutorial can be accessed using the command osxphotos tutorial via the command line. If you are interested in using OSXPhotos in your own code, see API_README.md for a description of the API as well as the example programs. The full documentation is available online and can also be accessed using the command osxphotos docs via the command line. Running osxphotos help will show help in the terminal. You can use osxphotos help COMMAND to get help on a command. For example, osxphotos help export. To search within the help of a specific command, use osxphotos help COMMAND TOPIC, for example, osxphotos help export sidecar.

If you have questions, would like to show off projects created with OSXPhotos, or if you just want to say hello, please use the GitHub discussions forum or the osxphotos subreddit on Reddit.

Command Line Usage

This package will install a command line utility called osxphotos that allows you to query the Photos database. Alternatively, you can also run the command line utility like this: python3 -m osxphotos

Usage: osxphotos [OPTIONS] COMMAND [ARGS]...

  OSXPhotos: the multi-tool for your Photos library.

  To get help on a specific command, use "osxphotos COMMAND --help" or
  "osxphotos help COMMAND"; for example, "osxphotos help export".

  To search help for a specific topic within a command, run "osxphotos help
  COMMAND TOPIC"; for example, "osxphotos help export keyword" to get help
  related to keywords when using the export command.

  To see the full documentation in your browser, run "osxphotos docs".

  Some advanced commands are hidden by default. To see all commands, run
  "OSXPHOTOS_SHOW_HIDDEN=1 osxphotos help". Some commands also have hidden
  options. These can be seen by running "OSXPHOTOS_SHOW_HIDDEN=1 osxphotos help
  COMMAND".

Options:
  -v, --version  Show the version and exit.
  -h, --help     Show this message and exit.

Commands:
  about          Print information about osxphotos including license.
  add-locations  Add missing location data to photos in Photos.app using...
  albums         Print out albums found in the Photos library.
  batch-edit     Batch edit photo metadata such as title, description,...
  compare        Compare two Photos libraries to find differences
  docs           Open osxphotos documentation in your browser.
  dump           Print list of all photos & associated info from the Photos...
  exiftool       Run exiftool on previously exported files to update metadata.
  export         Export photos from the Photos database.
  exportdb       Utilities for working with the osxphotos export database
  help           Print help; for help on commands: help <command>.
  import         Import photos and videos into Photos.
  info           Print out descriptive info of the Photos library database.
  inspect        Interactively inspect photos selected in Photos.
  install        Install Python packages into the same environment as...
  keywords       Print out keywords found in the Photos library.
  labels         Print out image classification labels found in the Photos...
  list           Print list of Photos libraries found on the system.
  orphans        Find orphaned photos in a Photos library
  persons        Print out persons (faces) found in the Photos library.
  places         Print out places found in the Photos library.
  push-exif      Write photo metadata to original files in the Photos library
  query          Query the Photos database using 1 or more search options;...
  repl           Run interactive osxphotos REPL shell (useful for...
  run            Run a python file using same environment as osxphotos.
  show           Show photo, album, or folder in Photos from UUID_OR_NAME
  sync           Sync metadata and albums between Photos libraries.
  template       Interactively render templates for selected photo.
  theme          Manage osxphotos color themes.
  timewarp       Adjust date/time/timezone of photos in Apple Photos.
  tutorial       Display osxphotos tutorial.
  uninstall      Uninstall Python packages from the osxphotos environment
  uuid           Print out unique IDs (UUID) of photos selected in Photos
  version        Check for new version of osxphotos.

To get help on a specific command, use osxphotos help COMMAND, for example, osxphotos help export to get help on the export command.

Some of the commands such as export and query have a large number of options. To search for options related to a specific topic, you can use osxphotos help COMMAND TOPIC. For example, osxphotos help export raw finds the options related to RAW files (search is case-insensitive):

Usage: osxphotos export [OPTIONS] ... DEST

  Export photos from the Photos database. Export path DEST is required.
  Optionally, query the Photos database using 1 or more search options; if
  more than one option is provided, they are treated as "AND" (e.g. search for
  photos matching all options). If no query options are provided, all photos
  will be exported. By default, all versions of all photos will be exported
  including edited versions, live photo movies, burst photos, and associated
  raw images. See --skip-edited, --skip-live, --skip-bursts, and --skip-raw
  options to modify this behavior.

Options that match 'raw':

--has-raw                    Search for photos with both a jpeg and
                             raw version
--skip-raw                   Do not export associated RAW image of a
                             RAW+JPEG pair.  Note: this does not skip RAW
                             photos if the RAW photo does not have an
                             associated JPEG image (e.g. the RAW file was
                             imported to Photos without a JPEG preview).
--convert-to-jpeg            Convert all non-JPEG images (e.g. RAW, HEIC,
                             PNG, etc) to JPEG upon export. Note: does not
                             convert the RAW component of a RAW+JPEG pair as
                             the associated JPEG image will be exported. You
                             can use --skip-raw to skip
                             exporting the associated RAW image of a
                             RAW+JPEG pair. See also --jpeg-quality and
                             --jpeg-ext. Only works if your Mac has a GPU
                             (thus may not work on virtual machines).