Google Photos Metadata Restorer

Restores original creation dates from Google Photos takeout JSON metadata files to image and video files. Essential for preserving correct timeline when uploading to services like Amazon Photos.

Problem

When downloading photos from Google Photos, file creation dates are set to the download date rather than the original photo date. This script extracts the original date from JSON metadata files and restores it.

Features

• Smart: Auto-discovers subdirectories, handles JSON naming variations/typos
• Efficient: Skips files with correct metadata, parallel processing
• Comprehensive: Updates EXIF metadata, file timestamps, GPS coordinates, descriptions
• Robust: Handles JPG, JPEG, PNG, HEIC images and MP4, MOV videos
• Detailed Reports: Generates timestamped summary, error, and no-JSON logs

Requirements

• Python 3.7+
• Pillow, piexif (pip install -r requirements.txt)
• exiftool (for videos/HEIC): brew install exiftool (macOS) or sudo apt-get install libimage-exiftool-perl (Linux)

Installation

# Optional: Create virtual environment
python3 -m venv .venv
source .venv/bin/activate  # macOS/Linux

# Install dependencies
pip install -r requirements.txt

# Install exiftool
brew install exiftool  # macOS

Usage

Step 1: Extract Google Photos Takeout Files

1. Download your Google Photos takeout files (they come as .zip or .tgz archives)
2. Extract all archives to a single folder (e.g., Takeout or Google Photos)
   • Extract all .zip or .tgz files to the same destination folder
   • The folder should contain subdirectories like Google Photos 1, Google Photos 2, etc.
   • Example structure:

     Takeout/
     ├── Google Photos 1/
     ├── Google Photos 2/
     ├── Google Photos 3/
     └── ...
     

Step 2: Run the Script

# Activate venv (if using)
source .venv/bin/activate

# Run script (generates summary report only)
python3 restore_metadata.py

# With verbose console logging
python3 restore_metadata.py --verbose

# Generate detailed debug log (errors + files without JSON)
python3 restore_metadata.py --debug

# Fix incorrect file extensions (e.g., rename .HEIC files that are actually JPEGs)
python3 restore_metadata.py --fix-extensions

# Recommended: Combine debug and extension fixing
python3 restore_metadata.py --debug --fix-extensions

Step 3: Enter Directory Path

When prompted, enter the path to the folder containing your extracted Google Photos files:

• Example: /Volumes/External Drive/Google Photos/Takeout
• Or: ~/Downloads/Takeout
• The script will automatically discover all subdirectories

What the Script Does

Once you provide the directory path, the script will:

• Auto-discover all subdirectories
• Find JSON metadata files (handles various naming patterns)
• Extract original photo date from photoTakenTime.timestamp
• Update EXIF metadata, file timestamps, GPS coordinates, descriptions
• Skip files that already have correct metadata
• Process directories in parallel (with automatic batching for large directories)

What Gets Updated

For Images (JPG, PNG, HEIC):

• EXIF: DateTimeOriginal, DateTimeDigitized, DateTime
• File creation/modification times
• GPS coordinates (if available in JSON)
• Image description (if available)

For Videos (MP4, MOV):

• CreateDate, ModifyDate, MediaCreateDate, MediaModifyDate
• File creation/modification times
• GPS coordinates (if available)
• Description (if available)

Output Files

Always Generated:

• metadata_restore_summary_YYYYMMDD_HHMMSS.txt - Detailed statistics per directory and overall totals

Generated with --debug flag:

• metadata_restore_debug_YYYYMMDD_HHMMSS.txt - Combined debug log containing:
  • All errors encountered (corrupted files, permission issues, etc.)
  • All files without JSON metadata
  • Organized by directory for easy investigation

Notes

• Files with correct metadata are automatically skipped
• Read-only files are skipped (check permissions if needed)
• Hidden files/directories (starting with .) are skipped
• Original files are modified in place (backup if needed)
• Works with any directory structure
• Extension fixing (--fix-extensions): Renames files with incorrect extensions (e.g., .HEIC files that are actually JPEGs). Only renames if target filename doesn't already exist.

Troubleshooting

"exiftool not found": Install exiftool (videos/HEIC will be skipped without it)

"No JSON metadata found": Some files may not have JSON files - these are logged for investigation

Read-only files: Check file permissions or grant Full Disk Access (macOS)