📈 Repo Statistics

📸 PhotoMigrator

This tool has been designed to Interact and Manage different Photo Services such as Google Photos, Synology Photos, Immich Photos, NextCloud Photos, Google Takeout & Apple iCloud Takeout, and 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.

The Tool supports multiple accounts for the same service, so you can migrate your assets between different accounts of the same service.

📸 Tool Screenshots

🌐 Web Interface

Automatic Migration Feature:

Automatic Migration Feature (Live Dashboard):

Google Takeout Feature:

iCloud Takeout Feature:

Synology Photos Feature:

Immich Photos Feature:

Other Features:

General Arguments:

Configuration Panel:

App Settings:

🖥️ Automatic Migration on Terminal

🌟 Main Modules:

🚀 1. Automatic Migration

The main use case is the Automatic Migration Feature to migrate all your photos and videos from one Photo cloud service to other, or between different accounts of the same service.

[!IMPORTANT] Since April 1, 2025, Google Photos can no longer be used by third-party apps as a full-library SOURCE for Automatic Migration because Google removed the legacy read scopes from the Library API. Use Google Takeout as --source instead. Google Photos remains usable as an upload target with the supported scopes.

[!TIP] Automatic Migration now also auto-detects raw Apple iCloud Takeout folders used as --source, preprocesses them first, and then migrates the resulting library to the target. If the local source contains ZIP files, they are unpacked first and the extracted folder is then classified as Google Takeout, iCloud Takeout, or a normal local folder. That automatic iCloud preprocessing enables Memories by default, and when a local source contains a Memories folder those collections are treated the same way as Albums.

[!TIP] For local-folder based migrations and uploads, you can exclude generated thumbnails or other unwanted content using glob patterns with --exclude-folders and --exclude-files.

Example: --exclude-folders @eaDir .@__thumb @Recycle --exclude-files SYNOFILE_THUMB* SYNOPHOTO_THUMB* SYNOPHOTO_FILM* Thumbs.db .DS_Store

[!NOTE] For more info you can check the feature documentation in below link:

(Automatic Migration Documentation)

🛠️ 2. Google Takeout Fixing

Other important feature included in the tool is the Google Takeout Fixing.

This feature has been designed to automatically analyze your Google Photos Takeout, extract all the information from the sidecar JSON files (or guess some missing information using heuristics algorithms) and embeds all the extracted info into each asset file using EXIF tags.

In this way your Media Library will be ready to be migrated to any other Cloud Photo services without losing any important info such as, Albums info, Original date, GPS location, Camera info, etc...

But this feature also helps you to organize and clean your Media Library removing duplicates, creating Year/Month folder structure, creating symbolic links for Albums assets, Auto renaming Albums to clean their names and include a prefix with the date of its assets, Process Motion/Live Pictures, etc...

The whole process is done in an automatic way and is divided in different steps (some of them are optionals).

[!NOTE] For more info you can check the feature documentation in below link:

(Google Takeout Fixing Documentation)

🍎 3. iCloud Takeout Fixing

Other important feature included in the tool is the iCloud Takeout Fixing.

This feature has been designed to process Apple iCloud Photos privacy exports, recover the original capture dates from Photo Details.csv, assign those dates to the exported assets, and rebuild Albums from Apple CSV manifests.

In this way your Media Library will be ready to be migrated to any other Cloud Photo services without losing important information such as Original date and Albums relationships.

But this feature also helps you to reconstruct the exported library structure in a more usable way, including optional Memories rebuilding when those manifests are present in the export.

The whole process is done in an automatic way and is independent from the cloud-service management modules.

[!NOTE] For more info you can check the feature documentation in below link:

(iCloud Takeout Fixing Documentation)

🖼️ 4. Google Photos / Synology Photos / Immich Photos / NextCloud Photos

Apart from the Automatic Migration, Google Takeout Fixing, and iCloud Takeout Fixing features, you can also use the tool to manage Google Photos and different Photo Cloud Services.

• Google Photos supports direct upload/download operations through the official API.
• Synology Photos, Immich Photos, and NextCloud Photos provide cloud management and migration operations.

Currently, the Features Supported per each Photo Cloud Service are:

[!NOTE] For more info you can check the feature documentation in below links:

• (Google Photos Documentation)

• (Synology Photos Documentation)

• (Immich Photos Documentation)

• (NextCloud Photos Documentation)

[!IMPORTANT]

• NextCloud Photos is available since v4.0.0 using WebDAV-based integration.

• Google Photos is available since v4.0.0 with partial support due current official API limitations. Since April 1, 2025, Google Photos full-library reads are no longer available through the public Library API, so use Google Takeout for migrations/downloads of a full library and Google Photos mainly as upload target.

🧩 5. Other Standalone Features

Finally, the Tool also contains Other Useful Standalone Features such as:

• Metadata fixing of any Photo Library in your local drive (not necessarily needs to be a Google Takeout folder)
• Library Organization features:
  • Manage Duplicates assets
  • Organize any local folder by capture date into year, year/month, year-month, or flatten
  • Splitting of assets with and without associated albums
  • Folder Structure (customizable) for 'Albums' and 'No Albums' folders
• Symbolic Links Support for Albums folders
  • Fix Symbolic Links Broken
• Homogenize Albums folder's name based on content

[!NOTE] For more info you can check the feature documentation in below link:

(Other Standalone Features Documentation)

🖥️ Tool Interfaces

🌐 1. Web Interface (New)

PhotoMigrator now includes a Web Interface that executes the same CLI arguments under the hood.

Main characteristics:

• Multi-tab UI separated by module:
  • Automatic Migration
  • Google Takeout
  • iCloud Takeout
  • Google Photos
  • Synology Photos
  • Immich Photos
  • NextCloud Photos
  • Other Features
• General/optional arguments available for all tabs.
• Automatic Migration and local-folder workflows support exclusion filters for unwanted folders/files such as @eaDir, .@__thumb, @Recycle, SYNOFILE_THUMB*, SYNOPHOTO_THUMB*, SYNOVIDEO_THUMB*, SYNOPHOTO_FILM*, Thumbs.db, ehthumbs.db, .DS_Store, or ._*.
• Real command preview + execution output in the browser.
• Backend powered by FastAPI + uvicorn on port 6078.

[!NOTE] You can access to the new Web Interface (demo) on this link:

PhotoMigrator Web Interface (demo)

Username: demo
Password: demo

Deploy Web Interface with Docker

The complete Docker guide for the Web Interface now lives in:

• Deploy Web Interface from Docker

That guide includes:

• Linux, Windows, and macOS instructions
• direct download commands for docker-compose.yml and .env
• a ready-to-use .env that works without mandatory edits for local use
• a clear split between mandatory, recommended, and optional customization

Quick start:

cd docker-web
docker compose pull
docker compose up -d

Then open:

• http://localhost:6078

🪟 2. Graphical User Interface (GUI) and Terminal Interactive User Interface (TUI)

PhotoMigrator includes two local interactive interfaces in addition to the Web Interface:

• Desktop GUI: a native windowed interface built with tkinter.
• Terminal TUI: an interactive terminal interface built with Textual.

Both interfaces expose the same high-level structure:

• Feature Selector
• Features Config
• General Arguments
• App Settings
• command preview, status panel, and execution log

Default launcher behavior:

• Running PhotoMigrator without arguments tries to open the Desktop GUI first.
• If the GUI cannot be started because tkinter or a graphical display is not available, PhotoMigrator falls back to the Terminal TUI.
• If neither interactive interface can be started, PhotoMigrator falls back to the CLI and shows the arguments descriptions (same output as --help).

Explicit launchers:

• PhotoMigrator --gui opens the Desktop GUI explicitly.
• PhotoMigrator --tui opens the Terminal TUI explicitly.
• PhotoMigrator --configuration-file /path/to/Config.ini can be combined with either launcher, or used on its own, to open the default interactive UI with a different configuration file preloaded.

Config file behavior in GUI/TUI:

• If no explicit configuration path is provided, both interfaces use ./Config.ini from the current execution folder, matching the classic CLI behavior.
• You can also change the file later inside General Arguments > Configuration File.

Typical use:

• Use the Desktop GUI on Windows, macOS, or Linux systems with graphical desktop access.
• Use the Terminal TUI on SSH sessions, server terminals, or environments where a graphical window is not available but the terminal supports interactive rendering.

2.1 Graphical User Interface (GUI):

2.2 Terminal Interactive User Interface (TUI):

⌨️ 3. Command Line Interface (CLI)

This Tool is based on commands given through the Command Line Interface (CLI), so it is important to know the syntax of that interface.

PhotoMigrator now also includes an interactive CLI TUI that mirrors the Web Interface structure much more closely:

• Feature Selector with the same top-level modules as the Web Interface
• General Arguments, Features Config, and App Settings views
• Dynamic forms for Automatic Migration, Google Takeout, iCloud Takeout, cloud-service actions, and standalone features
• Multi-account Features Config selectors for Google Photos, Synology Photos, Immich Photos, and NextCloud Photos
• Live command preview and in-terminal execution log panel

Quick launch:

python ./src/PhotoMigrator.py

This now opens the desktop GUI by default.

Force the CLI TUI explicitly:

python ./src/PhotoMigrator.py --tui

Open the desktop GUI explicitly:

python ./src/PhotoMigrator.py --gui

Open either interactive UI with an explicit configuration file:

python ./src/PhotoMigrator.py --gui --configuration-file ./Config.ini
python ./src/PhotoMigrator.py --tui --configuration-file ~/PhotoMigrator/custom.ini

Launcher fallback order when no arguments are provided:

• Desktop GUI
• CLI TUI
• Command-line help (--help)

You can check the whole list of features and arguments with the right syntax here: Command Line Interface (CLI)

Arguments Description

Check all arguments descriptions and usage examples in the Arguments Description or in the shorter version.

📘 All Documentation Links

• Configuration File
• Command Line Interface (CLI)
• Arguments Description
• Automatic Migration Feature
• Google Takeout Management
• iCloud Takeout Management
• Google Photos Management
• Synology Photos Management
• Immich Photos Management
• NextCloud Photos Management
• Other Features
• GPTH Tool Pipeline Description
• Docker Deployment Documentation

📘 Docker Deployments Documentation Links

• Deploy Web Interface from Docker
• Deploy CLI Interface from Docker

▶️ Execution Methods

There are four different methods to execute this Tool:

• Execute from Compiled Binaries
• Execute from Source Repository
• Deploy Web Interface (from docker)
• Deploy CLI Interface (from docker)

Below tables show the pros and cons of each method together with a comparative rating of each one of them for you to decide which one fits best with your needed:

🆚 Execution Methods Comparison

🟢 Easiest way ⭐ Recommended 🔴 More difficult

🆚 Execution Methods Comparison Rating

💾 Download

Download the tool either for Linux, MacOS or Windows (for both x64 and arm64 architectures) or Docker version (platform & architecture independent) as you prefer, directly from following links:

• Latest Stable Release
• Pre-Release
• All Releases

Or check the Changelog to choose any specific release.

[!NOTE]
The Tool is Multi-Platform and Multi-Architecture, and has been designed to be run directly from Windows systems, MacOs or within a Linux Server or NAS such as Synology NAS (Compatible with DSM 7.0 or higher), so feel free to download the version according to your system.

You can also execute the Tool from a Docker container or from sources files for a better compatibility. In below sections you can find the execution instructions to run the Tool from the different methods.

Compiled binary names are currently platform-specific:

• Windows: PhotoMigrator.exe
• macOS: PhotoMigrator_vx.y.z_macos_<arch>.command
• Linux / Synology SSH: PhotoMigrator_vx.y.z_linux_<arch>.bin

[!IMPORTANT]
On macOS, downloaded unsigned binaries may be blocked by Gatekeeper on first launch. If that happens, run: chmod +x ./PhotoMigrator_vx.y.z_macos_<arch>.command && xattr -dr com.apple.quarantine ./PhotoMigrator_vx.y.z_macos_<arch>.command and then execute that same .command file again from Terminal or Finder. Replace x.y.z and <arch> with the exact version and architecture you downloaded.

⚙️ Configuration File

In order to connect to the different Photo Cloud Services, you must configure the connection settings using the Configuration file Config.ini provided with the Tool.

When running the Web Interface in Docker/Compose/Kubernetes, you can also override the same cloud-service keys through environment variables. Supported config keys can be provided directly as KEY=value or through Docker-secret style KEY_FILE=/path/to/secret. Runtime precedence is: environment variable > Config.ini > template default. This is useful for IMMICH_URL, IMMICH_API_KEY_ADMIN, SYNOLOGY_*, NEXTCLOUD_*, GOOGLE_PHOTOS_*, etc.

You can see how to configure the Configuration File in this help section: Configuration File

📝 CHANGELOG

The Historical Change Log can be checked in the following link: Changelog

📅 ROADMAP

The Planned Roadmap for futures releases can be checked in the following link: Planned Roadmap

🛡️ CODE OF CONDUCT

By participating in this project, you agree to abide by our Code of Conduct.

📢 Disclaimer

[!CAUTION]

• ⚠️ The project is under very active development.
• ⚠️ Expect bugs and breaking changes.

📊 Repository activity

📈 Star History

👥 Contributors

If you want to Contribute to this project please, first read the file CONTRIBUTING.md

🤝 Related Projects

• Synology Photos Create albums full of precious moments, share your perfectly framed photos, and store them securely on your Synology NAS.
• Immich Photos High performance self-hosted photo and video management solution.
• NextCloud Photos Your memories under your control.
• Google Photos Takeout Helper (GPTH) Script that organizes the Google Takeout archive into one big chronological folder.
• Exiftool Metadata information reader/writer.

🎖️ Credits

I hope this can be useful for any of you. Enjoy it!

(c) 2024-2026 by Jaime Tur (@jaimetur).
Part of this Tool is based on GPTH Tool by TheLastGimbus/Wacheee and v4.x.x by Xentraxx

🙏 Donation / Sponsor

If you consider that this Tool has helped you, you can also consider donating me with a ☕
I spent a lot of time developing this Tool for free, so donations will contribute to motivate me to continue working on this project 💖