Apple Photos

Apple Photos

Query and export from the macOS Photos library. Three subcommands cover the typical workflow: discover people, search with filters, export to a folder.

Subcommands

people

List face clusters with photo counts.

apple-photos people --limit 30
apple-photos people --include-unknown

query

Search photos by person, album, keyword, and date range.

apple-photos query --person "<NAME>" --after 2026-01-01 --limit 20 --json
apple-photos query --album "Favorites" --newest-first --limit 10
apple-photos query --keyword "vacation" --before 2025-12-31

Filters: --person, --album, --keyword, --after, --before, --favorite, --edited, --movies, --newest-first

export

Copy matched photos to a destination folder. Never modifies the Photos library.

apple-photos export ~/Desktop/exports --person "<NAME>" --after 2026-01-01 --limit 30
apple-photos export ~/Desktop/exports --album "Favorites" --edited
apple-photos export ~/Desktop/exports --person "<NAME>" --dry-run

Add --edited to prefer edited versions. Use --dry-run to preview without copying.

Workflow

1. Run people to confirm the face label exists.
2. Run query to search and preview matches.
3. Run export to copy a batch to a working folder.
4. Use vision or local tools to score, sort, crop, and retouch the exports.

Guardrails

• Never modify the Photos library directly — export copies only.
• Face labels can be incomplete. Spot-check results.
• For large exports, start with --dry-run or a narrow date range.

Fallbacks

• If face labels are incomplete, query by album/date and review manually.
• If a photo only exists in Google Photos or shared links, use browser retrieval.
• If the user wants deep retouching, export first, then use external editors.

Requirements

• macOS with Photos.app
• osxphotos Python library (auto-installed via UV on first run)