Photo Organizer

Organize your iPhone photos by date, location, and type. Then back them up to the cloud. Always copies files - your originals stay safe.

Quick Start (5 minutes)

1. Install

git clone <repo-url>
cd photo-organizer
uv sync --all-extras

2. Configure

Set your preferred directories once:

# Create config file
uv run photo-organizer config init

# Edit it
uv run photo-organizer config edit

Set these values:

input_dir: ~/Pictures              # Where your photos are
output_dir: ~/Organized_Photos     # Where to put organized photos

upload:
  provider: google_drive           # or google_photos, s3
  remote_path: PhotoBackups        # Folder in cloud

3. Organize

# Preview what will happen
uv run photo-organizer organize --dry-run

# Actually do it (copies files, originals stay safe)
uv run photo-organizer organize

4. Backup to Cloud

# First, set up cloud credentials (see below)
cp .env.example .env
# Edit .env with your credentials

# Upload
uv run photo-organizer upload

That's it!

---

Using Friendly CLI (Even Easier)

If you have friendly installed:

# Setup
friendly setup              # Install dependencies
friendly config:init        # Create config

# Organize
friendly organize           # Preview (dry-run)
friendly organize:go        # Actually organize

# Backup
friendly upload             # Upload to cloud
friendly backup:drive       # Organize + upload in one go

---

Cloud Setup

Google Drive / Google Photos

1. Go to https://console.cloud.google.com
2. Create a project → Enable "Google Drive API" (or "Photos Library API")
3. Credentials → Create Credentials → OAuth 2.0 Client ID → Desktop app
4. Download JSON → save as ~/.config/photo-organizer/google_credentials.json

First upload will open browser for login. Token is saved for future runs.

S3 / AWS / MinIO / Wasabi

Edit .env:

S3_BUCKET=my-backup-bucket
S3_REGION=us-east-1
S3_ACCESS_KEY=your-key
S3_SECRET_KEY=your-secret

# For non-AWS (optional):
# S3_ENDPOINT_URL=https://s3.wasabisys.com

---

Commands Reference

Organize

uv run photo-organizer organize --dry-run     # Preview
uv run photo-organizer organize               # Organize (copies files)
uv run photo-organizer organize --no-location # Skip GPS lookup (faster)

Upload

uv run photo-organizer clouds                 # List providers
uv run photo-organizer upload                 # Upload (uses config)
uv run photo-organizer upload google_drive -p "Backups/2024"
uv run photo-organizer upload s3 -p "photos/2024"

Config

uv run photo-organizer config show            # See current settings
uv run photo-organizer config edit            # Edit config file
uv run photo-organizer config set --key input_dir --value ~/Photos

---

What It Does

Input: Your messy Photos folder with thousands of files scattered in subfolders

~/Pictures/
├── IMG_1234.jpg
├── Vacation/
│   ├── IMG_2345.jpg
│   └── Summer/
│       └── IMG_3456.jpg
├── Download/
│   └── photo.jpg
└── ... (thousands more in random folders)

Output: Clean organization (flat structure by date/type):

Organized_Photos/
├── Photos_Camera/           # Your camera photos
│   └── 2024/
│       ├── 01_January/
│       │   └── Tokyo/       # GPS location (if enabled)
│       └── 02_February/
├── Photos_Downloaded/       # Saved from apps/web
├── Videos_Camera/           # Videos you recorded
├── Videos_Downloaded/       # Saved videos
├── Screenshots/             # Screenshots
└── RAW_Photos/              # RAW files

Files are renamed with dates: 2024-01-15_14-30-00_iPhone.jpg

✅ Nested folders are fully supported - it scans all subdirectories recursively and flattens the structure

---

Project Structure

photo_organizer/
├── config.py          # Configuration management
├── cli.py             # Command-line interface
├── organizer.py       # Main organization logic
├── cloud_upload.py    # Google Drive, Photos, S3 uploaders
└── ...

Configuration files:
├── ~/.config/photo-organizer/config.yml  # Your defaults
├── ./.env                                 # Cloud credentials (don't commit!)
└── ./photo-organizer.yml                  # Project-specific defaults

---

FAQ

Q: Will it delete my original photos?
A: No. It only copies files. Originals stay exactly where they are.

Q: Can I run it multiple times?
A: Yes. It skips files that are already organized (by content check).

Q: How do I add a new cloud provider?
A: See photo_organizer/cloud_upload.py - add a class inheriting from CloudUploader.

Q: What if I don't want location lookup?
A: Set use_location: false in config, or use --no-location flag.

---

Requirements

• Python 3.10+
• uv (package manager)

License

MIT