v0.1.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.

View on GitHub ↓ Download ZIP

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.

12 089

files in the test export

99.99%

successfully dated & organized

JSON matching strategies

What it handles

🗂

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.

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
        

Output structure

Photos_Organized/

├── 2022/ ← YYYY/MM/

│ ├── 06/

│ └── 11/

├── 2023/

├── albums/

│ ├── Cats 🐱/

│ └── Summer Trip/

├── unknown_date/ ← no recoverable date

└── suspicious_date/ ← future timestamp

Also by the author

Once your Takeout is organized, you might want to compress it. Shrinkify deduplicates and compresses your media library using hardware-accelerated encoding. The two tools pair naturally: gphotos-fixer organizes, Shrinkify cleans up.