Google Photos to Apple Photos Migration Tool

A simple tool that helps you move your photos from Google Photos to Apple Photos while keeping all your photo information intact (dates, locations, descriptions, etc.).

What This Tool Does

When you download your photos from Google Photos (called a "Takeout"), they come with all your photo information stored in separate text files. Apple Photos can't read these files, so your photos would lose their dates, locations, and other details.

This tool fixes that problem by:

• ✅ Preserving Photo Dates: Your photos keep their original capture dates
• ✅ Keeping GPS Locations: Location data stays with your photos
• ✅ Maintaining Descriptions: Any captions or descriptions you added are preserved
• ✅ Organizing Albums: Your album structure from Google Photos is maintained
• ✅ Handling Special Cases: Separates photos that couldn't be processed for manual review

Before You Start

You'll need to install two things on your Mac:

1. ExifTool (Required)

This is a small program that helps edit photo information. Install it using Homebrew:

# First install Homebrew if you don't have it (copy and paste this in Terminal)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Then install ExifTool
brew install exiftool

2. Python (Usually Already Installed)

Most Macs come with Python. You need version 3.8 or newer. Check by typing this in Terminal:

python3 --version

If you see a number like 3.8.x or higher, you're good to go!

How to Use the Tool

Step 1: Download Your Google Photos

1. Go to Google Takeout
2. Select only "Photos and videos"
3. Choose "Export once" and download format
4. Click "Create export"
5. Download the ZIP file(s) when ready

Step 2: Run the Tool

Option A: Simple Mode (Recommended)

1. Open Terminal on your Mac
2. Navigate to where you downloaded this tool:

   cd ~/Downloads/ExifMetadataFormatter

3. Run the tool with your ZIP file:

   python3 takeout_processor.py --zip-files ~/Downloads/takeout-*.zip --output ~/Desktop/ImportToApplePhotos

Option B: If You Already Extracted the ZIP

python3 takeout_processor.py --extracted-dir ~/Downloads/Takeout --output ~/Desktop/ImportToApplePhotos

Option C: Use the Visual Interface

python3 takeout_processor.py --gui

This opens a window where you can click buttons instead of typing commands.

Step 3: Import to Apple Photos

1. Open Apple Photos
2. Go to File → Import
3. Select the folder: ~/Desktop/ImportToApplePhotos
4. Click "Review for Import"
5. Click "Import All New Items"

What You'll Get

After running the tool, you'll find two folders:

Main Folder

Contains all your photos that were successfully processed with complete information:

• Original photo dates preserved
• GPS locations intact
• Descriptions and tags included
• Ready for Apple Photos import

"unmapped" Folder

Contains photos that couldn't be automatically processed (usually special effects or burst photos):

• These need manual review
• You can still import them, but they might not have all the original information
• Typically only 3-4% of your photos

Example Commands

Process a single ZIP file:

python3 takeout_processor.py --zip-files ~/Downloads/takeout-20240101.zip --output ~/Desktop/MyPhotos

Process multiple ZIP files:

python3 takeout_processor.py --zip-files ~/Downloads/takeout-*.zip --output ~/Desktop/MyPhotos

Test run (see what would happen without actually doing it):

python3 takeout_processor.py --zip-files ~/Downloads/takeout-*.zip --output ~/Desktop/MyPhotos --dry-run

Success Rate

This tool typically processes 96-98% of photos successfully. The remaining 2-4% are usually:

• Special Google Photos effects
• Burst photo sequences
• Photos with unusual naming patterns

These are safely stored in the "unmapped" folder for you to review.

Troubleshooting

"ExifTool not found" error:

• Make sure you installed ExifTool: brew install exiftool

"Permission denied" error:

• Make sure you have write permission to your output folder
• Try using a folder in your home directory like ~/Desktop/

Photos are missing dates after import:

• Some photos might be in the "unmapped" folder
• Check that folder and import those separately

Large ZIP files taking forever:

• The tool works with files of any size, but very large exports (100GB+) take time
• You can stop and restart the process safely

Getting Help

If you run into problems:

1. Check the log file: Look for takeout_processing.log in your output folder
2. Try the dry-run mode: Add --dry-run to see what would happen without making changes
3. Use the GUI: Try --gui for a visual interface
4. Check file permissions: Make sure you can write to the output folder

Testing

This tool includes a comprehensive test suite to ensure reliable metadata processing and prevent regressions.

Test Coverage:

• Metadata Recovery Strategies: Tests all 6 processing strategies that achieve 100% success rate
• File Pattern Recognition: Validates handling of different Google Photos filename formats
• Edge Cases: Tests Unicode album names, malformed data, and error conditions
• Integration: End-to-end workflow verification

Running Tests:

# Run all tests
python3 test_takeout_processor.py

# Run with detailed test runner
python3 run_tests.py

Continuous Integration: All pull requests automatically run the full test suite via GitHub Actions. PRs cannot be merged unless all tests pass.

Technical Details

• Supported file types: JPG, PNG, HEIC, MP4, MOV, GIF, TIFF, BMP
• Metadata preserved: EXIF, IPTC, XMP data
• Album structure: Maintains Google Photos folder organization
• Unicode support: Handles international characters in album names
• Safe processing: Original files are never modified, only copies are created

---