Transform your chaotic Google Photos Takeout into organized photo libraries with proper dates, albums, and metadata.

Acknowledgment: This project is based on the original work by TheLastGimbus. We are grateful for their foundational contributions to the Google Photos Takeout ecosystem. Also thank you to @jaimetur for your significant contributions to this fork!

When you export photos from Google Photos using Google Takeout, you get a mess of folders with weird .json files and broken timestamps. This tool:

• ✅ Organizes photos chronologically with correct dates
• ✅ Restores album structure with multiple handling options
• ✅ Fixes timestamps from JSON metadata and EXIF data
• ✅ Writes GPS coordinates and timestamps back to media files (requires ExifTool for non-JPEG formats)
• ✅ Removes duplicates automatically
• ✅ Handles special formats (HEIC, Motion Photos, etc.)
• ✅ Fixes mismatches of file name and mime type if google photos renamed e.g. a .heic to .jpeg (but mime type remains heic), due to storage saver mode, we can fix this mismatch

Please note the wiki is not yet complete but contains more technical details if you are looking for more information about how everything works.

Download the latest executable from releases

Package Managers:

• Arch Linux: yay -S gpth-bin (Maintained by TheLastGimbus, so this does not work with my fork. Just kept it here in case he merges my fork into the original project)

Building from Source:

git clone https://github.com/Xentraxx/GooglePhotosTakeoutHelper.git
cd GooglePhotosTakeoutHelper
dart pub get
dart compile exe bin/gpth.dart -o gpth

ExifTool (required for metadata handling):

• Windows:

  # With Chocolatey (automatically adds to PATH):
  choco install exiftool

  • Or download from exiftool.org and rename exiftool(-k).exe to exiftool.exe
  • Place exiftool.exe in your system PATH, or place it in the same folder as gpth.exe
  • Also place the exiftool_files folder next to gpth.exe
• Mac:

  brew install exiftool

  • Or download from exiftool.org and place exiftool in PATH or same folder as gpth
• Linux:

  sudo apt install libimage-exiftool-perl

  • Or download from exiftool.org and place exiftool in PATH or same folder as gpth

Note: If ExifTool is not found in PATH or the same directory as GPTH, the tool will fall back to basic EXIF reading with limited format support. EXIF writing for non-JPEG formats requires ExifTool.

7-Zip (optional — faster for for automatic ZIP extraction):

GPTH can extract your Google Takeout ZIP files automatically if 7-Zip is available on your system.

• Windows:

  # With Chocolatey (automatically adds to PATH):
  choco install 7zip

  • Or download the installer from 7-zip.org and install it
  • After installation, ensure 7z.exe is in your system PATH, or place it in the same folder as gpth.exe
• Mac:

  brew install sevenzip

  • Or download from 7-zip.org
• Linux:

  sudo apt install 7zip

Note: If 7-Zip is not found, GPTH will fall back to Dart's built-in ZIP extractor. The built-in extractor is significantly slower for very large archives.

1. Go to Google Takeout
2. Deselect all, then select only Google Photos
3. Download all ZIP files

GPTH now supports automatic extraction directly from ZIP files:

1. Keep your ZIP files from Google Takeout
2. When running GPTH in interactive mode, select "Select ZIP files from Google Takeout"
3. GPTH will automatically extract, merge, and process all files
4. Original ZIP files are preserved; temporary extracted files are cleaned up automatically

The automatic ZIP processing is recommended for most users as it:

• Reduces manual work and potential errors
• Ensures proper file merging across multiple ZIP files
• Automatically cleans up temporary files

The biggest downside is, that you need the processing power to extract on the device you run gpth. If this is an issue, choose manual extraction.

1. Unzip all files manually
2. Merge them so you have one unified "Takeout" folder
3. When running GPTH, select "Use already extracted folder"

⚠️ Note that the files will be moved from the input folder during processing, so keep the original ZIPs as backup!

Interactive Mode (recommended for beginners):

• Windows: Double-click gpth.exe
• Mac/Linux: Run ./gpth-macos or ./gpth-linux in terminal

Follow the prompts to select input/output folders and options

GPTH offers several ways to handle your Google Photos albums:

What it does: Creates symbolic links from album folders to files in ALL_PHOTOS. The original files are moved to ALL_PHOTOS, and symlinks are created in album folders.

Advantages:

• Saves maximum disk space (no duplicate files)
• Maintains album organization
• Fast processing
• Better compatibility with cloud services and file type detection
• Works across all platforms (Windows, Mac, Linux)

Disadvantages:

• Requires symbolic link support (most modern systems support this)
• Some older applications may not follow symlinks properly

Best for: Most users who want space efficiency and better compatibility with modern applications and cloud services.

What it does: The opposite of shortcut mode. Files remain in their original album folders, and shortcuts are created in ALL_PHOTOS pointing to the album locations.

Advantages:

• Preserves album-centric organization
• Original files stay in their natural album context
• Good for users who primarily browse by albums

Disadvantages:

• ALL_PHOTOS becomes dependent on album folders
• If a photo is in multiple albums, only one copy exists (in first album found)
• Shortcuts in ALL_PHOTOS may break if album folders are moved

Best for: Users who primarily organize and browse photos by albums rather than chronologically.

What it does: Creates actual file copies in both ALL_PHOTOS and album folders. Each photo appears as a separate physical file in every location.

Advantages:

• Works across all systems and applications
• Complete independence between folders
• Safe for moving/copying folders between devices
• Album photos remain accessible even if ALL_PHOTOS is deleted

Disadvantages:

• ⚠️ Uses significantly more disk space (multiplied by number of albums)
• Slower processing due to file copying
• Changes to one copy don't affect others

Best for: Users who need maximum compatibility, plan to share folders across different systems, or have plenty of disk space.

What it does: Creates a single ALL_PHOTOS folder with all files, plus an albums-info.json file containing metadata about which albums each file belonged to.

Advantages:

• Most space-efficient option
• Programmatically accessible album information
• Simple folder structure
• Perfect for developers or automated processing

Disadvantages:

• No visual album folders
• Requires custom software to utilize album information
• Not user-friendly for manual browsing

Best for: Developers, users migrating to photo management software that can read JSON metadata, or those who don't care about visual album organization.

What it does: Doesn't create Albums folder. All photos from each album and from year folders are moved to ALL_PHOTOS with all files organized chronologically. All files are moved to ALL_PHOTOS regardless of their source location. If one file belong to more than 1 albums, then only 1 copy will be kept in ALL_PHOTOS

Advantages:

• Simplest processing
• Fastest execution
• Clean, single-folder result
• No complex album logic
• No data loss - all files are moved

Disadvantages:

• ⚠️ Completely loses album organization
• ⚠️ No way to recover album information later

Best for: Users who don't care about album organization and just want all photos in chronological order.

What it does: Ignores albums entirely and creates only ALL_PHOTOS with files from year folders (Photos from YYYY) organized chronologically. Album folders are ignored: files that exist only in album folders (and not in any year folder) are permanently deleted from disk and will not appear anywhere in the output.

Advantages:

• Simplest processing
• Fastest execution
• Clean, single-folder result

Disadvantages:

• ⚠️ Permanently deletes all album-only files — these are gone forever
• ⚠️ Completely loses album organization
• ⚠️ No way to recover album-only content after running

Best for: Users who are certain all their photos exist in year folders and simply want to skip album processing entirely.

For automation, headless systems, or advanced users:

gpth --input "/path/to/takeout" --output "/path/to/organized" --albums "shortcut"

The --json-dates argument should be a JSON dictionary that must have as key the full filepath (in unix format) and the value must be a dictionary with at least the key oldestDate which contains the date for the given filepath.

Example:

{
  "/data/2012-08-05_161346-EFFECTS.jpg": {
    "OldestDate": "2012-08-05T00:00:00+02:00"

  },
  "/data/2012-08-07_090832.JPG": {
    "OldestDate": "2012-08-05T15:42:06+02:00"
}

Google Photos has an option of 'data saving' which will compress images to JPEG format but retain the original filename extension. Additionally, some web-downloaded images may have incorrect extensions (e.g., a file named .jpeg may actually be .heif internally).

GPTH natively writes EXIF data to files with JPEG signatures, while other formats require ExifTool. Files with mismatched extensions can cause ExifTool to fail, so GPTH provides several extension fixing strategies.

You can configure extension fixing behavior with:

The TIFF Problem: Many RAW camera formats (CR2, NEF, ARW, etc.) are based on the TIFF specification internally. Standard MIME type detection often identifies these as image/tiff, which could cause the tool to rename photo.CR2 to photo.CR2.tiff, potentially breaking camera software compatibility.

The JPEG Complexity: While JPEG files are generally safe to rename, the conservative mode provides an extra safety net for users who prefer minimal changes to their photo collections.

ExifTool Dependencies: When extensions don't match content, ExifTool operations fail. The extension fixing resolves this by ensuring filenames accurately reflect file content, enabling proper metadata writing.

NOTE: Some RAW formats are TIFF-based internally and contain TIFF headers - the extension fixing modes are designed to avoid incorrectly renaming these files.

Scenario 1: Google Photos Data Saver

• Original file: vacation_sunset.heic (HEIC format from iPhone)
• Google Photos compresses it to JPEG but keeps name: vacation_sunset.heic
• File header shows: JPEG, Extension suggests: HEIC
• standard mode renames to: vacation_sunset.jpg

Scenario 2: Camera RAW File

• Camera file: DSC_0001.NEF (Nikon RAW)
• MIME detection might identify as: TIFF (since NEF is TIFF-based)
• standard mode: Skips (protects RAW files)
• conservative mode: Skips (protects RAW files)
• none mode: No change (leaves as-is)

Scenario 3: Web Download

• Downloaded as: image.png
• Actually contains: JPEG data
• standard mode renames to: image.jpg
• conservative mode: Skips (avoids touching JPEG content)

Basic usage:

gpth --input "~/Takeout" --output "~/Photos" --albums "shortcut"

Move files with year folders:

gpth --input "~/Takeout" --output "~/Photos" --divide-to-dates 1

Full metadata processing:

gpth --input "~/Takeout" --output "~/Photos" --transform-pixel-mp --albums "duplicate-copy"

Separate partner shared media with date organization:

gpth --input "~/Takeout" --output "~/Photos" --divide-partner-shared --divide-to-dates 1

Fix dates in existing folder:

gpth --fix "~/existing-photos"

GPTH uses multiple methods to determine correct photo dates:

1. JSON metadata (most accurate)
2. EXIF data from photo files
3. Filename patterns (Screenshot_20190919-053857.jpg, etc.)
4. Aggressive matching for difficult cases
5. Folder year extraction (Photos from 2005 → January 1, 2005)

Removes identical files using content hashing, keeping the best copy (shortest filename, most metadata).

Extracts location data and timestamps from JSON files and writes them to media file EXIF data for compatibility with photo viewers and other applications.

• Motion Photos: Pixel .MP/.MV files can be converted to .mp4
• HEIC/RAW support: Handles modern camera formats
• Unicode filenames: Properly handles international characters
• Large files: Optional size limits for resource-constrained systems

Separates partner shared media from personal uploads for better organization:

• Automatic Detection: Identifies partner shared photos from JSON metadata
• Separate Folders: Moves partner shared media to PARTNER_SHARED folder
• Date Organization: Applies same date division structure to partner shared content
• Album Compatibility: Works with all album handling modes

Enable partner sharing separation:

gpth --input "~/Takeout" --output "~/Photos" --divide-partner-shared

• Multiple date-based folder structures
• Preserve or reorganize album structure
• Move files efficiently from input to organized output structure
• Group Special Folders (Trash, Archive, Locked Folder) into Special Folder directory
• Group Untitled Albums into Untitled Albums directory

• The tool detects if a previous execution was interrupted, and if so, when running again over the same output folder, it tries to resume from the step where it was interrupted.
• For this function to work, the input and ouput folders should be the same as the previous execution.

• Find the whole changelog file here

"No photos found": Make sure you have a unified Takeout folder structure with "Photos from YYYY" folders.

Permission errors: Run with administrator/sudo privileges if moving files across drives.

Memory issues: Use --limit-filesize for systems with limited RAM.

Encoding errors: Some JSON files may have encoding issues; the tool handles most cases automatically.

Windows: Creation time updates require administrator privileges.

macOS: You may need to allow the executable in Security & Privacy settings.

Linux: Ensure ExifTool is installed for full functionality.

• Immich: Self-hosted Google Photos alternative
• PhotoPrism: AI-powered photo management
• Syncthing: Sync photos across devices while preserving dates

Standard file managers reset photo dates when moving files. Use Simple Gallery to preserve timestamps.

• PhotoMigrator: Complete Migratin tool that uses GPTH 4.x.x, and has been designed to Interact and Manage different Photos Cloud services. Allow users to do an Automatic Migration from one Photo Cloud service to other or from one account to a new account of the same Photo Cloud service.
• Google Keep Exporter: Export Google Keep notes to Markdown

Note: This tool moves files by default to avoid using extra disk space. Always keep backups of your original Takeout files!