v0.4.0 · MIT · Python 3.10+
gphotos-fixer
Rescue your Google Photos Takeout export. Handles every broken JSON naming variant, Windows path limit, and timestamp corruption others miss.
The Problem
Google Takeout exports are a mess. JSON sidecar files get their names truncated at random lengths. Windows MAX_PATH silently breaks glob(). Duplicate photo copies share a single metadata file. Timestamps end up as today's date. Most tools fail silently on these edge cases — or refuse to start at all.
📁 Files12,089Files in the test export
✅ Success Rate99.99%successfully dated & organized
🧩 Methods6JSON matching strategies
Features
🗂 Date-based structure
Organizes files into YYYY/MM/ folders with correct modification times.
📁 Album preservation
Keeps album folders intact under
albums/ without flattening your library.🔍 Broken JSON names
Matches
.suppl.json, .supplemen.json, .supplemental-met.json, and more — including Windows-truncated paths.🪞 Duplicate detection
MD5 hash check skips identical files and renames conflicting ones instead of overwriting.
🏷 3-tier date fallback
JSON → EXIF (via Pillow) → filename pattern. If all fail, the file lands in
unknown_date/.🔬 Dry-run mode
Preview exactly what would be copied before committing — no disk writes, no surprises.
📦 Flat mode
--flat fixes dates in any photo folder, not just a Takeout export — handy after an SD card transfer scrambles your timestamps.💻 Cross-platform
gphotos-fixer is a CLI program that can run on Windows, macOS and Linux.
Usage
Requires Python 3.10+. Install Pillow for EXIF support (optional but recommended).
# Clone and install
git clone https://github.com/nazimcanislam/gphotos-fixer.git
cd gphotos-fixer
pip install Pillow
# Interactive mode
python -m gphotos_fixer
# Non-interactive
python -m gphotos_fixer --input "/path/to/Takeout/Google Photos" --output "/path/to/Photos_Organized"
# Dry run — no files written
python -m gphotos_fixer --input ... --output ... --dry-run
# Flat mode — not a Takeout export, just a photo folder
python -m gphotos_fixer --input ... --output ... --flat
Output Structure
Photos_Organized/
├── 2022/← YYYY/MM/
│ ├── 06/
│ └── 11/
├── 2023/
├── albums/
│ ├── Cats 🐱/
│ └── Summer Trip/
├── unknown_date/← no recoverable date
└── suspicious_date/ ← future timestamp