CloudPhotoMigrator to move your photos between different Photo Cloud Services

[jaimetur]

Repo Statistics

CloudPhotoMigrator

This tool has been designed to Interact and Manage different Photos Cloud services, and allow users to do an Automated Migration from one Photo Cloud service to other or from one account to a new account of the same Photo Cloud service.

Currently, the Supported Photo Cloud Services are:

• Google Photos Takeout

  • Unpack your Takeout Zip files.
  • Process .json files to fix metadata (including creation date and time) of all your assets.
  • Merge Live picture with separate files (.HEIC and .MP4).
  • Separate your assets per Albums (if belong to any album).
  • Organize your assets in a year/month structure for a better organization.
  • Create Symbolic Links for assets within any Album (to save disk space).
  • Detect and remove duplicates.

• Synology Photos - Features included:

  • Upload Album(s)
  • Upload ALL (from folder)
  • Download Album(s)
  • Download ALL (into folder)
  • Remove ALL Assets
  • Remove ALL Albums
  • Remove Empty Albums
  • Remove Duplicates Albums

• Immich Photos - Features included:

  • Upload Album(s)
  • Upload ALL (from folder)
  • Download Album(s)
  • Download ALL (into folder)
  • Remove ALL Assets
  • Remove ALL Albums
  • Remove Empty Albums
  • Remove Duplicates Albums
  • Remove Orphans Assets

• Apple Photos
  (not available yet but is on the ROADMAP.md for next release)

• Google Photos
  (not available yet but is on the ROADMAP.md for next release)

Apart from Manage the different Photo Cloud Services, the Tool also contains some other useful features such as:

• Metadata fixing of any Photo Library in your local drive (not necesarely needs to be a Google Takeout folder)
• Library Organization features:
  • Manage Duplicates assets
  • 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 folders name based on content
• Remove Empty Albums in Photo Cloud Services
• Remove Duplicates Albums in Photo Cloud Services

Live Dashboard Preview:

Download:

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

• Latest Stable Release
• Pre-Release
• All Releases

Configuration File:

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

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

Command Line Interface (CLI):

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

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

All Documentation Links:

• Configuration File
• Command Line Interface (CLI)
• Automated Migration Feature
• Google Takeout Management
• Synology Photos Management
• Immich Photos Management
• Other Features

Note

The Tool is Multi-Platform and Multi-Architecture, and has been designed to be run directly 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.

Execution Methods:

There are three different methods to execute this Tool:

• From Compiled Binaries
• From Docker Container
• From Source Repository

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

• Execution Methods Comparison

  Execution Method	Instructions Link	Difficulty	Pros	Cons
  Compiled Binaries	Instructions	🟢 Easiest way	✅ Only basic knowledge on command line commands needed.	❌ Platform and architecture dependent. ❌ Need basic knowledge of running command line instructions. ❌ Some anti-virus may detect the tool as suspicious in Windows systems.
  Docker Container	Instructions	⭐ Recommended	✅ Platform and architecture independent. ✅ Easy configuration via docker.config file (RELEASE_TAG, TIMEZONE). ✅ Automatically pulls latest image if RELEASE_TAG=latest.	❌ Need intermediate knowledge of running command line instructions. ❌ Need to install Docker (if not already installed). ❌ All paths given as arguments must be relative to the execution folder.
  Source Repository	Instructions	🔴 More difficult	✅ Platform and architecture independent.	❌ Need advance knowledge of running command line instructions. ❌ Need to install Git and Python 3.8+ (if not already installed). ❌ Need to pull the source repository again to update to a new release.

• Execution Methods Comparison Rating

  Feature	Compiled Binaries easiest way	Docker Container recommended	Source Repository more difficult
  Platform and architecture independence	⭐☆☆☆☆	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐
  Ease of updating to new release	⭐⭐⭐☆☆	⭐⭐⭐⭐⭐	⭐☆☆☆☆
  Allow paths arguments point outside execution folder	⭐⭐⭐⭐⭐	⭐☆☆☆☆	⭐⭐⭐⭐⭐
  No Requires Technical knowledge (Command line syntax)	⭐⭐⭐⭐⭐	⭐⭐⭐☆☆	⭐☆☆☆☆
  No Requires additional tools/software	⭐⭐⭐⭐⭐	⭐⭐⭐☆☆	⭐☆☆☆☆
  No Risk of Antivirus alert (especially on Windows)	⭐⭐☆☆	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐
  Average Rating	⭐⭐⭐⭐☆ (3.5)	⭐⭐⭐⭐☆ (3.7)	⭐⭐⭐☆☆ (3.0)

Main Use Case: Automated Migration Feature

Note

Automated Migration Feature

From version 3.0.0 onwards, the Tool supports a new Feature called 'Automated Migration'.

Use the argument '--source' to select the <SOURCE> client and the argument '--target' to select <TARGET> client for the Automated Migration Process to Pull all your Assets (including Albums) from the <SOURCE> Cloud Service and Push them to the <TARGET> Cloud Service (including all Albums that you may have on the Cloud Service).

• Possible values for:

  • <SOURCE> : ['synology-photos', 'immich-photos']-[id] or <INPUT_FOLDER> (id=[1, 2] to select which account to use from the Config.ini file).
  • <TARGET> : ['synology-photos', 'immich-photos']-[id] or <OUTPUT_FOLDER> (id=[1, 2] to select which account to use from the Config.ini file).

• The idea is complete above list to allow also Google Photos and Apple Photos (iCloud), so when this is done, the allowed values will be:

  • <SOURCE> : ['synology-photos', 'immich-photos', 'google-photos', 'apple-photos']-[id] or <INPUT_FOLDER> (id=[1, 2] to select which account to use from the Config.ini file).
  • <TARGET> : ['synology-photos', 'immich-photos', 'google-photos', 'apple-photos']-[id] or <OUTPUT_FOLDER> (id=[1, 2] to select which account to use from the Config.ini file).

If you ommit the suffix -[id], the tool will assume that account 1 will be used for the specified client (ie: --source=synology-photos means that Synology Photos account 1 will be used as <SOURCE> client.)

Also, you can ommit the suffix -photos in both <SOURCE> and <TARGET> clients, so, you can just use --source=synology --target=immich to set Synology Photos account 1 as <SOURCE> client and Immich Photos account 1 as <TARGET> client.

By default, the whole Migration process is executed in parallel using multi-threads (it will detect automatically the number of threads of the CPU to set properly the number of Push workers). The Pull worker and the different Push workes will be executed in parallel using an assets queue to guarantee that no more than 100 assets will be temporarily stored on your local drive, so you don't need to care about the hard disk space needed during this migration process.

By default, (if your terminal size has enough width and heigh) a Live Dashboard will show you all the details about the migration process, including most relevant log messages, and counter status. You can disable this Live Dashboard using the flag '-dashboard=false or --dashboard=false'.

Additionally, this Automated Migration process can also be executed sequentially instead of in parallel, using flag --parallel=false, so first, all the assets will be pulled from and when finish, they will be pushed into , but take into account that in this case, you will need enough disk space to store all your assets pulled from service.

Finally, you can apply filters to filter assets to pull from <SOURCE> client. The available filters are:

• by Type:
  • flag: -type, --filter-by-type
    • Valid values are [image, video, all]
• by Dates:
  • flags:
    • -from, --filter-from-date
    • -to, --filter-to-date
  • Valid values are in one of those formats:
    • dd/mm/yyyy
    • dd-mm-yyyy
    • yyyy/mm/dd
    • yyyy-mm-dd
    • mm/yyyy
    • mm-yyyy
    • yyyy/mm
    • yyyy-mm
    • yyyy
• by Country:
  • flag: -country, --filter-by-country
    • Valid values are any existing country in the <SOURCE> client.
• by City:
  • flag: -city, --filter-by-city
    • Valid values are any existing city in the <SOURCE> client.
• by Person:
  • flag: -person, --filter-by-person
    • Valid values are any existing person in the <SOURCE> client.

Warning

If you use a local folder <INPUT_FOLDER> as source client, all your Albums should be placed into a subfolder called 'Albums' within <INPUT_FOLDER>, creating one Album subfolder per Album, otherwise the tool will no create any Album in the target client.

Example:
<INPUT_FOLDER>/Album1
<INPUT_FOLDER>/Album2

Important

It is important that you configure properly the file 'Config.ini' (included with the tool), to set properly the accounts for your Photo Cloud Service.

ROADMAP:

v3.2.0

Release Date: (estimated)

• Alpha version : 2025-04-07
• Beta version : 2025-04-14
• Release Candidate: 2025-04-25
• Official Release : 2025-04-30

TODO:

• Add option to filter assets in all Immich/Synology/LocalFolder Actions:
  • by Type
  • by Dates
  • by Country
  • by City
  • by Person
• Added new flag -type, --filter-by-type = [image, video, all] to select the Asset Type to download (default: all)
• Added new flag -from, --filter-from-date <FROM_DATE> to select the Initial Date of the Assets to download
• Added new flag -to, --filter-to-date <TO_DATE> to select the Final Date of the Assets to download
• Added new flag -country, --filter-by-country <COUNTRY_NAME> to select the Country Name of the Assets to download
• Added new flag -city, --filter-by-city <CITY_NAME> to select the City Name of the Assets to download
• Added new flag -person, --filter-by-person <PERSON_NAME> to select the Person Name of the Assets to download
• Added new flag -parallel, --parallel-migration =[true,false] to select the Migration Mode (Parallel or Sequential). Default: true (parallel)
• Included Live Dashboard in sequential Automated Migration
• Minor bugs fixing
• Test sequential Automated Migration
• Test Filters in Automated Migration Feature
• Test Filters in other Synology/Immich Features

v4.0.0:

Release Date: (estimated)

• Alpha version : (No estimated date)
• Beta version : (No estimated date)
• Release Candidate: (No estimated date)
• Official Release : (No estimated date)

TODO:

• Include Apple Support (initially just for downloading)
  • Create Class ClassApplePhotos with the same methods and behaviour as ClassSynologyPhotos or ClassImmichPhotos. (volunteers are welcomed)
  • -adAlb, --apple-download-albums
  • -adAll, --apple-download-all
  • -auAlb, --apple-upload-albums
  • -auAll, --apple-upload-all
• Include native support for Google Photos through API
  (See: https://max-coding.medium.com/loading-photos-and-metadata-using-google-photos-api-with-python-7fb5bd8886ef)
  • Create Class ClassGooglePhotos with the same methods and behaviour as ClassSynologyPhotos or ClassImmichPhotos. (volunteers are welcomed)
  • -gdAlb, --google-download-albums
  • -gdAll, --google-download-all
  • -guAlb, --google-upload-albums
  • -guAll, --google-upload-all
• Allow Google Photos and Apple Photos as TARGET in AUTOMATED-MODE
• Update Documentation
• Update README.md
• Update RELEASES-NOTES.md

Credits

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

(c) 2024-2025 by Jaime Tur (@jaimetur).
Part of this Tool is based on GPTH Tool by TheLastGimbus

Donation / Sponsor:

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

[TheLastGimbus]

Oh okay... nice what you got there 👀

[newbie441]

Question really, can I run cloudphotomigrator on two instances of takeout. I.e. mine and my wife's. At separate times. What will happen to the file structure of the takeout completed folder of the two instances, can they be merged etc.

[jaimetur]

Question really, can I run cloudphotomigrator on two instances of takeout. I.e. mine and my wife's. At separate times. What will happen to the file structure of the takeout completed folder of the two instances, can they be merged etc.

Sure, you can run it on different Takeouts. Each instance will generate a separated output folder with the same name of the original Takeout followed by a suffix and a timestamp.

If after that you want to merge both output folders you can do it easily, just move/copy one folder into the other and if there are some files in common they will be overwritten.

If both instances were created with the same settings, then you should have the same folder structure in both output folders, so the merge will have the same folder structure as well.