Photo Sorter

A locally-hosted web application for browsing and sorting your macOS Photos library by file size. Perfect for finding large files to clean up disk space.

Why?

The macOS Photos app doesn't let you sort by file size. Since the Photos library is stored as an opaque .photoslibrary package, you can't easily browse files by size in Finder either. This tool solves that problem.

Features

• Sort by size - Find your largest photos and videos instantly
• Filter by type - View all media, photos only, or videos only
• Size thresholds - Filter to show only files above a certain size (1MB, 10MB, 100MB, etc.)
• iCloud support - Shows cloud status for files not downloaded locally
• Delete photos - Remove files directly (moves to Recently Deleted, recoverable for 30 days)
• Export photos - Save copies to any folder
• Reveal in Photos - Jump to any photo in the Photos app
• Dark theme - Easy on the eyes
• Responsive design - Works on any screen size

Requirements

• macOS 10.15 (Catalina) or later
• Python 3.10+
• Photos app with a library

Installation

1. Clone the repository

   git clone https://github.com/yourusername/photo-sorter.git
   cd photo-sorter

2. Run the app

   ./run.sh

   This will:

   • Create a virtual environment
   • Install dependencies
   • Start the server
   • Open your browser to http://127.0.0.1:8080

3. Grant permissions (first run only)

   You may need to grant Terminal/Python access to Photos:

   • Go to System Settings > Privacy & Security > Photos
   • Enable access for Terminal (or your terminal app)

Usage

1. Start the app with ./run.sh
2. Browse your photos sorted by size (largest first by default)
3. Click any photo to see details and actions
4. Use filters to narrow down results
5. Delete or export files as needed
6. Press Ctrl+C in terminal to stop the server

How It Works

┌─────────────────────────────────────────┐
│         Web Browser (localhost)          │
│      Grid view, filters, actions         │
└────────────────────┬────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────┐
│            FastAPI Backend               │
│    Serves API, generates thumbnails      │
└────────────────────┬────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────┐
│          osxphotos Library               │
│   Reads Photos database (read-only)      │
└────────────────────┬────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────┐
│     ~/Pictures/Photos Library.photoslibrary     │
└─────────────────────────────────────────┘

• Reading: Uses osxphotos to read the Photos database
• Thumbnails: Generated on-the-fly from original files using Pillow
• Actions: Delete/export/reveal use AppleScript to interact with Photos.app
• Caching: Photo metadata is cached for 5 minutes for performance

Privacy & Security

• 100% local - No data leaves your machine
• Read-only access - The app only reads your Photos database; modifications go through Photos.app
• No analytics - No tracking, no external requests
• No accounts - No login, no cloud services

Project Structure

photo_sorter/
├── app/
│   ├── main.py              # FastAPI server
│   ├── photos_service.py    # osxphotos wrapper
│   ├── routes/
│   │   ├── photos.py        # List/filter endpoints
│   │   └── actions.py       # Delete/export/reveal
│   └── static/
│       ├── index.html       # Frontend
│       ├── style.css        # Styles
│       └── app.js           # Frontend logic
├── requirements.txt
├── run.sh                   # Startup script
└── README.md

API Endpoints

Endpoint	Method	Description
/api/photos	GET	List photos with pagination, sorting, filtering
/api/photos/stats	GET	Library statistics
/api/photos/{uuid}	GET	Single photo details
/api/photos/refresh	POST	Refresh metadata cache
/api/thumbnail/{uuid}	GET	Photo thumbnail
/api/actions/{uuid}/delete	POST	Delete photo
/api/actions/{uuid}/export	POST	Export photo
/api/actions/{uuid}/reveal	POST	Reveal in Photos app

Troubleshooting

"Failed to load photos" error

• Ensure Photos app has been opened at least once
• Grant Terminal access in System Settings > Privacy & Security > Photos

Thumbnails not loading

• Some files may be iCloud-only (shown with cloud badge)
• For videos, ensure ffmpeg is installed: brew install ffmpeg

Permission denied errors

• On macOS Sonoma+, you may need Full Disk Access for Terminal

Tech Stack

• Backend: Python, FastAPI, osxphotos, Pillow
• Frontend: Vanilla HTML/CSS/JavaScript
• No build step: Just run and go

Credits

• osxphotos by Rhet Turnbull - The excellent library that makes this possible

License

MIT License - See LICENSE for details