PhotoScript

What is PhotoScript

PhotoScript provides a python wrapper around Apple Photos applescript interface. With PhotoScript you can interact with Photos using python. Runs only on MacOS. Tested on MacOS Catalina.

PhotosScript is limited by Photos' very limited AppleScript dictionary.

Compatibility

Designed for MacOS Catalina/Photos 5. Preliminary testing on Big Sur/Photos 6 beta shows this should work on Big Sur as well. Photos' AppleScript interface has changed very little since Photos 2 (the earliest version I have access to). This package should work with most versions of Photos but some methods may not function correctly on versions earlier than Photos 5. If you find compatibility issues, open an issue or send a PR.

Installation

You can install via pip:

python3 -m pip install photoscript

To install via the source code:

Install uv if not already installed
Clone the repo: git clone git@github.com:RhetTbull/PhotoScript.git
Change to the directory: cd PhotoScript
Run uv pip install -r pyproject.toml.

If you want to develop code for PhotoScript, see README_DEV.md.

Example

""" Simple example showing use of photoscript """

import photoscript

photoslib = photoscript.PhotosLibrary()

photoslib.activate()
print(f"Running Photos version: {photoslib.version}")

album = photoslib.album("Album1")
photos = album.photos()

for photo in photos:
    photo.keywords = ["travel", "vacation"]
    print(f"{photo.title}, {photo.description}, {photo.keywords}")

new_album = photoslib.create_album("New Album")
photoslib.import_photos(["/Users/rhet/Downloads/test.jpeg"], album=new_album)

photoslib.quit()

Documentation

Full documentation here.

Additional documentation about Photos and AppleScript available on the wiki.

Testing

Tested on MacOS Catalina, Photos 5 with 100% coverage.

Limitations

Photos' AppleScript interface is very limited. For example, it cannot access information on faces in photos nor can it delete a photo. PhotoScript is thus limited. PhotoScript works by executing AppleScript through an Objective-C bridge from python. Every method call has to do a python->Objective C->AppleScript round trip; this makes the interface much slower than native python code. This is particularly noticeable when dealing with Folders which requires significant work arounds.

Where possible, PhotoScript attempts to provide work-arounds to Photos' limitations. For example, Photos does not provide a way to remove a photo from an album. PhotoScript does provide a Album.remove() method but in order to do this, it creates a new album with the same name as the original, copies all but the removed photos to the new album then deletes the original album. This simulates removing photos and produces the desired effect but is not the same thing as removing a photo from an album.

osxphotos: Python package that provides read-only access to the Photos library including all associated metadata.
PhotoKit: Experimental Python package for accessing the macOS Photos.app library via Apple's native PhotoKit framework.

Dependencies

Contributors ✨

Thanks goes to these wonderful people (emoji key):

_{David Haberthür}
📖

_{André Anjos}
🤔 🐛

_oPromessa
💻

This project follows the all-contributors specification. Contributions of any kind welcome!

Metadata

Release files for photoscript 0.6.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for photoscript 0.6.0
File	Size	Uploaded
photoscript-0.6.0.tar.gz	29.9 kB	Sep 27, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for photoscript 0.6.0
File	Interpreter	ABI	Platform	Reset
photoscript-0.6.0-py3-none-any.whl 27.9 kB Sep 27, 2026	Python 3	none	any	Details

Total release size: 57.9 kB

Release files / photoscript-0.6.0.tar.gz

Download URL	photoscript-0.6.0.tar.gz
Size	29.9 kB
Tags	Source
SHA-256 checksum How to use checksums	`0d1bee0106c0252ae77d5d0a458e39155d6d46b8f225c4cffb6be329cc8b39d0`
BLAKE2b-256 checksum How to use checksums	`5d6d66f0eb039123b7eb58338946eaf053c2f46e308ec1dd4b28cf63012ff576`
Upload date	Sep 27, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.9.2`

Release files / photoscript-0.6.0-py3-none-any.whl

Download URL	photoscript-0.6.0-py3-none-any.whl
Size	27.9 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`c3afc92e8eac61994d4bc92ed282d19f1eced967882d88738dffe69bbed67b62`
BLAKE2b-256 checksum How to use checksums	`c792e155a91dfe1b167aff7ad6a8e272956be0f97950eb4b9df29a3082516550`
Upload date	Sep 27, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.9.2`