# rhettbull/osxphotos

**Attribution required: if you use, quote, or summarise this content, you must credit and link back to [awesome-repositories.com](https://awesome-repositories.com/repository/rhettbull-osxphotos).**

3,317 stars · 143 forks · Python · mit

## Links

- GitHub: https://github.com/RhetTbull/osxphotos
- awesome-repositories: https://awesome-repositories.com/repository/rhettbull-osxphotos.md

## Topics

`apple` `apple-photos` `apple-photos-export` `library-photos` `macos` `macosx` `osx` `photos` `photos-database` `photos-export` `pictures` `python`

## Description

osxphotos is a command-line interface tool and programmatic database interface designed for managing and exporting media from Apple Photos libraries. It provides a bridge to the underlying system database, allowing for the automation of batch operations and the retrieval of technical metadata.

The project distinguishes itself through a metadata-driven export system that uses custom templates to organize files into directory hierarchies. It can extract machine-learning data—including aesthetic scores and optical character recognition—and synchronize metadata across different libraries using unique file fingerprints.

Its broader capabilities include comprehensive metadata management, such as batch editing EXIF data and generating XMP or JSON sidecars. The tool also supports asset querying via filters, duplicate photo identification, and the ability to trigger native actions within the photo application via scripts.

The project is implemented in Python.

## Tags

### Data & Databases

- [Template-Based Filename Generators](https://awesome-repositories.com/f/data-databases/data-serialization-formats/output-formatting-systems/template-based-filename-generators.md) — Uses a custom templating engine to determine output directories and filenames based on photo metadata.
- [Apple Photos Database Interfaces](https://awesome-repositories.com/f/data-databases/apple-photos-database-interfaces.md) — Acts as a programmatic bridge for executing SQL queries and retrieving technical metadata from the photo database.
- [Export Criteria Filtering](https://awesome-repositories.com/f/data-databases/data-export/export-restrictions/export-criteria-filtering.md) — Restricts exported media based on query options such as keywords, albums, date ranges, and image types. ([source](https://github.com/RhetTbull/osxphotos/blob/main/README.md))
- [Template-Based Exports](https://awesome-repositories.com/f/data-databases/data-export/template-based-exports.md) — Arranges exported files into custom directory hierarchies and filenames using a metadata-driven template system. ([source](https://github.com/RhetTbull/osxphotos#readme))
- [Media Asset Metadata Updates](https://awesome-repositories.com/f/data-databases/file-metadata-services/media-asset-metadata-updates.md) — Updates titles, descriptions, keywords, and location data for multiple selected files simultaneously. ([source](https://github.com/RhetTbull/osxphotos/blob/main/CHANGELOG.md))
- [Metadata-Driven Path Templating](https://awesome-repositories.com/f/data-databases/metadata-driven-path-templating.md) — Converts metadata into formatted strings for filenames or paths using a custom templating language. ([source](https://github.com/RhetTbull/osxphotos/blob/main/API_README.md))
- [Library Querying](https://awesome-repositories.com/f/data-databases/metadata-filtering/photo/library-querying.md) — Provides advanced querying and filtering of photo libraries using keywords, dates, people, and other media attributes. ([source](https://github.com/RhetTbull/osxphotos/blob/main/API_README.md))
- [Programmatic Asset Retrieval](https://awesome-repositories.com/f/data-databases/metadata-filtering/photo/programmatic-asset-retrieval.md) — Provides a programmatic interface to retrieve assets and AI-generated metadata from the photo database.
- [SQL Query Interfaces](https://awesome-repositories.com/f/data-databases/sql-query-interfaces.md) — Directly interfaces with the Apple Photos SQLite database to read and query media metadata.
- [Data Transformation Filters](https://awesome-repositories.com/f/data-databases/custom-reporting-engines/template-based-reports/data-transformation-filters.md) — Allows user-defined functions to transform metadata strings during the template rendering process. ([source](https://github.com/RhetTbull/osxphotos/blob/master/examples/template_filter.py))
- [Template Function Injections](https://awesome-repositories.com/f/data-databases/data-export/template-based-exports/template-function-injections.md) — Injects custom functions into export templates to calculate filenames or metadata values based on asset properties. ([source](https://github.com/RhetTbull/osxphotos/blob/master/examples/template_function.py))
- [Dataset Filtering and Search](https://awesome-repositories.com/f/data-databases/data-querying/table-item-filters/dataset-filtering-and-search.md) — Searches for photos using filters such as date ranges, keywords, album membership, and detected text. ([source](https://github.com/RhetTbull/osxphotos/blob/main/CHANGELOG.md))
- [Synchronization State Tracking](https://awesome-repositories.com/f/data-databases/database-backed-configurations/synchronization-state-tracking.md) — Maintains a local database to track exported assets, enabling incremental synchronization of new or modified files.
- [File Fingerprinting Systems](https://awesome-repositories.com/f/data-databases/file-fingerprinting-systems.md) — Computes unique hashes of original files to identify duplicate images across different libraries.
- [Raw SQL Execution](https://awesome-repositories.com/f/data-databases/raw-sql-execution.md) — Allows the execution of custom SQL commands directly against the underlying Apple Photos database. ([source](https://github.com/RhetTbull/osxphotos/blob/master/API_README.md))

### Graphics & Multimedia

- [Photo and Media Export](https://awesome-repositories.com/f/graphics-multimedia/photo-and-media-export.md) — Copies original or edited images and videos to a custom file structure based on metadata and templates. ([source](https://github.com/RhetTbull/osxphotos/blob/main/API_README.md))
- [Photo Export Workflow Managers](https://awesome-repositories.com/f/graphics-multimedia/photo-export-workflow-managers.md) — Extracts media into custom folder structures with formatted filenames and metadata sidecars using templates.
- [Apple Photos Library Automations](https://awesome-repositories.com/f/graphics-multimedia/apple-photos-library-automations.md) — Automates batch operations and album management within the Apple Photos ecosystem using scripts.
- [Digital Asset Managers](https://awesome-repositories.com/f/graphics-multimedia/digital-asset-managers.md) — Manages digital assets by updating EXIF data, correcting timestamps, and syncing keywords across collections.
- [EXIF Metadata Handling](https://awesome-repositories.com/f/graphics-multimedia/exif-metadata-handling.md) — Reads image metadata using internal database records or by interfacing with an external utility. ([source](https://github.com/RhetTbull/osxphotos/blob/main/API_README.md))
- [Metadata Writing](https://awesome-repositories.com/f/graphics-multimedia/exif-metadata-handling/metadata-writing.md) — Writes keywords, persons, and GPS location directly into image files using an external utility. ([source](https://github.com/RhetTbull/osxphotos/blob/master/API_README.md))
- [Metadata Managers](https://awesome-repositories.com/f/graphics-multimedia/image-editing-processing/photo-management-systems/metadata-managers.md) — Provides tools for updating image titles, descriptions, and location data via EXIF metadata management. ([source](https://github.com/RhetTbull/osxphotos/blob/main/README.md))
- [Photo Library Programmatic Interfaces](https://awesome-repositories.com/f/graphics-multimedia/photo-library-programmatic-interfaces.md) — Provides a programmatic interface to retrieve assets and metadata from the photo library for custom automation. ([source](https://github.com/RhetTbull/osxphotos#readme))
- [Photo Management Systems](https://awesome-repositories.com/f/graphics-multimedia/photo-management-systems.md) — Provides programmatic access to the Apple Photos library to retrieve assets and technical metadata. ([source](https://github.com/RhetTbull/osxphotos/blob/master/API_README.md))
- [Image Format Conversion](https://awesome-repositories.com/f/graphics-multimedia/image-format-encoding/image-format-conversion.md) — Transforms non-JPEG images into JPEGs during the export process with adjustable quality settings. ([source](https://github.com/RhetTbull/osxphotos#readme))
- [Library Comparison Tools](https://awesome-repositories.com/f/graphics-multimedia/library-comparison-tools.md) — Identifies differences between separate photo collections by analyzing image fingerprints and associated metadata. ([source](https://github.com/RhetTbull/osxphotos/blob/main/API_README.md))
- [Media Album Organization](https://awesome-repositories.com/f/graphics-multimedia/media-album-organization.md) — Automates the creation of albums and the organization of assets within the photo library. ([source](https://github.com/RhetTbull/osxphotos/blob/main/API_README.md))
- [External Metadata File Generation](https://awesome-repositories.com/f/graphics-multimedia/media-file-tagging/external-metadata-file-generation.md) — Generates XMP or JSON sidecar files containing metadata for compatibility with external asset management software. ([source](https://github.com/RhetTbull/osxphotos#readme))
- [Photo Album Management](https://awesome-repositories.com/f/graphics-multimedia/photo-album-management.md) — Creates new albums or adds specific assets to existing albums within the photo application. ([source](https://github.com/RhetTbull/osxphotos/blob/master/API_README.md))
- [Photo Date Adjustment](https://awesome-repositories.com/f/graphics-multimedia/photo-date-adjustment.md) — Changes the date and time of files based on filename patterns or fixed offsets to correct timing errors. ([source](https://github.com/RhetTbull/osxphotos/blob/main/CHANGELOG.md))
- [Photo Library Comparison Tools](https://awesome-repositories.com/f/graphics-multimedia/photo-library-comparison-tools.md) — Analyzes two separate photo libraries to determine which assets are missing or identical. ([source](https://github.com/RhetTbull/osxphotos/blob/main/CHANGELOG.md))
- [Photo Library Import](https://awesome-repositories.com/f/graphics-multimedia/photo-library-import.md) — Adds external files to a library while preserving metadata from sidecars, folder names, or filename dates. ([source](https://github.com/RhetTbull/osxphotos/blob/main/CHANGELOG.md))
- [Photo Library Metadata Synchronizers](https://awesome-repositories.com/f/graphics-multimedia/photo-library-metadata-synchronizers.md) — Copies metadata and location data between different libraries to maintain consistency across collections. ([source](https://github.com/RhetTbull/osxphotos/blob/main/CHANGELOG.md))
- [Duplicate Photo Detectors](https://awesome-repositories.com/f/graphics-multimedia/photo-management-systems/duplicate-photo-detectors.md) — Locates possible duplicate photos by comparing original file size, creation date, and dimensions. ([source](https://github.com/RhetTbull/osxphotos/blob/main/API_README.md))
- [Photo Library Synchronizers](https://awesome-repositories.com/f/graphics-multimedia/photo-management-systems/photo-library-synchronizers.md) — Identifies duplicates and synchronizes missing assets and metadata across two separate photo collections. ([source](https://github.com/RhetTbull/osxphotos/blob/main/README.rst))

### Artificial Intelligence & ML

- [AI Analysis Retrieval](https://awesome-repositories.com/f/artificial-intelligence-ml/ai-analysis-retrieval.md) — Extracts AI-generated metadata including aesthetic scores, categorization labels, and OCR text from the photo library. ([source](https://github.com/RhetTbull/osxphotos/blob/master/API_README.md))
- [Optical Character Recognition](https://awesome-repositories.com/f/artificial-intelligence-ml/optical-character-recognition.md) — Identifies and extracts text from photos using optical character recognition with configurable confidence thresholds. ([source](https://github.com/RhetTbull/osxphotos/blob/main/API_README.md))

### Part of an Awesome List

- [Photo Management](https://awesome-repositories.com/f/awesome-lists/media/photo-management.md) — Automates batch edits and organizes albums within the Apple Photos library.

### Development Tools & Productivity

- [Apple Photos CLI Tools](https://awesome-repositories.com/f/development-tools-productivity/apple-photos-cli-tools.md) — Provides a comprehensive command-line interface for exporting, querying, and managing the Apple Photos library.
- [CLI Development Helpers](https://awesome-repositories.com/f/development-tools-productivity/cli-development-helpers.md) — Provides a framework for wrapping internal functions into full command-line applications with standardized options. ([source](https://github.com/RhetTbull/osxphotos/blob/main/API_README.md))
- [Photo](https://awesome-repositories.com/f/development-tools-productivity/metadata-exporters/photo.md) — Extracts image metadata into XMP or JSON sidecars and embeds EXIF data into exported files.
- [Photo Library Metadata Querying](https://awesome-repositories.com/f/development-tools-productivity/search-query-filters/photo-library-metadata-querying.md) — Searches for photos and videos using filters and outputs results to formats like JSON. ([source](https://github.com/RhetTbull/osxphotos/blob/main/README.rst))

### Operating Systems & Systems Programming

- [Application Scripting Interfaces](https://awesome-repositories.com/f/operating-systems-systems-programming/kernel-core-internals/system-programming-primitives/system-abstractions/native-interoperability-bindings/native-system-integrations/application-scripting-interfaces.md) — Triggers native actions and batch operations within the Apple Photos app using system scripts. ([source](https://github.com/RhetTbull/osxphotos/blob/main/README.rst))

### Testing & Quality Assurance

- [Export State Tracking](https://awesome-repositories.com/f/testing-quality-assurance/general-testing-utilities/test-reporters/external-result-reporters/tap-result-exporters/test-report-exporters/asynchronous-export-management/export-state-tracking.md) — Tracks state using a local database to export only new or changed files during subsequent runs. ([source](https://github.com/RhetTbull/osxphotos/blob/main/README.md))