How To Backup Google Photos To Your Computer With gphotos-sync

gphotos-sync is a command line tool for backing up Google Photos (including separate albums) using the Google Photos Library API, for Linux, macOS and Windows. Use it periodically to grab all newly added photos, keeping a complete Google Photos backup on a server or desktop.

This tool is specially useful after Google's announcement that Google Photos will stop syncing to Drive starting July 10, 2019, which means that some tools for backing up Google Photos to your computer will stop working (affecting Insync for instance, a commercial Google Drive client that runs on Linux, macOS and Windows).

gphotos-sync can backup all the photos an user has uploaded to Google Photos, as well as additional photos created automatically using Google Photos, like animations, panoramas, movies, enhanced photos, or collages.

This application is only for Google Photos download / backup purposes. It cannot upload photos to Google Photos.

The first full sync creates 2 directories:

  • photos, which contains all Google Photos and videos organized in a year/month subfolder structure (photo/YYYY/MM)
  • albums, which contains a folder hierarchy representing the set of albums and shared albums in your library (albums/YYYY/MM Original Album Name). Since this folder contains the same photos as those in photos/, the images in albums/ are symbolic links to the photos from photos/

Subsequent runs of gphotos-sync with the same root folder will refresh the local copy with any new photos added to your Google Photos since the last scan. It will not update any photos modified in Google Photos though, because there's no way to find out the modification date of images from Google Photos.

It's also worth noting that the Google Photos Library API strips GPS data from the images EXIF information (there's an open issue for this). The gphotos-sync page includes an work-around for this issue, explained here, which I did not try.

gphotos-sync features / options include:

  • download all your images and videos from Google Photos, including those created automatically by Google Photos (animations, panoramas, movies, enhanced photos, or collages)
  • grab all new photos added to your Google Photos account since the previous sync
  • optionally only download and synchronize a single album (using --album "ALBUM NAME")
  • compare the images in your Google Photos account with a local folder, like a previous backup. The comparison does not require that the files are arranged in the same folders, it uses meta-data in the files such as create date and exif UID to match pairs of items (use --compare-folder "COMPARE_FOLDER") See this link for more information
  • delete the index database and re-scan everything (--flush-index)
  • optionally re-scan the entire library, ignoring the last scan date (--rescan)
  • check for the existence of files marked as already downloaded and re-download any missing ones. Use this if you have deleted some local files (--retry-download)
  • skip videos when syncing (--skip-video)
  • set the start and end date of the files to sync in the format YYYY-MM-DD (--start-date START_DATE / --end-date END_DATE)
  • scrape the Google Photos website for location metadata and add it to the local files' EXIF metadata (--get-locations)

Before using gphotos-sync, I recommend reading its known issues and limitations.

Installing and setting up gphotos-sync


See how to install gphotos-sync on Windows.

This tool uses the Google Photos API, and requires you to create a new Google Cloud project, enable the Photos API for your project, and setup OAuth 2.0 for it, so you can use your own API key, to avoid running into API limitations. There are still API limitations, but this way you'll be the only one using it. This first part of the guide below is for installing gphotos-sync, and the second part about using your own API key with gphotos-sync (it doesn't work without this).

Install gphotos-sync using pipenv on Linux:

1. Install pip3:

  • Debian, Ubuntu, Linux Mint, Pop!_OS, elementary OS:
sudo apt install python3-pip

  • Fedora:
sudo dnf install python3-pip

  • Arch Linux, Manjaro:
sudo pacman -S python-pip

  • openSUSE:
sudo zypper install python3-pip

2. Export ~/.local/bin in PATH if you haven't already (that's where the executables for packages installed using pip3 are stored):

  • for Bash:
echo "export PATH=\"\$PATH:\$HOME/.local/bin\"" >> ~/.bashrc

. ~/.bashrc

  • for Zsh:
echo "export PATH=\"\$PATH:\$HOME/.local/bin\"" >> ~/.zshrc

. ~/.zsh

3. Install pipenv, create a folder called gphotos-sync in your home directory, and install gphotos-sync using pipenv:

python3 -m pip install pipenv
mkdir ~/gphotos-sync
cd ~/gphotos-sync
pipenv install gphotos-sync

You can now run gphotos-sync, e.g.:

pipenv run gphotos-sync

You need to run this command in the ~/gphotos-sync folder (so you'd have to cd ~/gphotos-sync, then use pipenv run gphotos-sync). You may use a different folder/path, but remember to replace all occurrences of ~/gphotos-sync with your custom location throughout this guide.


Create a Google Cloud project, enable the Photos Library API and create an OAuth client ID:

1. Create a new Google Cloud project

Go to https://console.cloud.google.com/cloud-resource-manager and create a new project.

For help with this step, see the Google Cloud documentation for creating a project https://cloud.google.com/resource-manager/docs/creating-managing-projects

2. Go to https://console.cloud.google.com/apis/library?project=_, select a project, then search for the Photos Library API and enable it for this project.

The Google Cloud help for enabling APIs can be found here: https://cloud.google.com/apis/docs/enable-disable-apis

3. Go to https://console.cloud.google.com/, make sure the correct project is selected from the top dropdown menu, then click on APIs & Services in the sidebar, and finally click Credentials in the sidebar. Create an Create OAuth client ID. When asked to choose the application type, select "Other".

You can see the complete procedure for setting up OAuth 2.0 with your new project on https://support.google.com/cloud/answer/6158849

4. Once the client ID is created, download it as client_secret.json (so rename it, as it will have a longer name) and save it under the application configuration directory:

  • ~/Library/Application Support/gphotos-sync/ under Mac OS X
  • ~/.config/gphotos-sync/ under Linux
  • C:\Users\<username>\AppData\Local\gphotos-sync\gphotos-sync\ under Windows

Now it's time to run the initial full Google Photos backup to your computer. To do that, you'll need to run pipenv run gphotos-sync in the ~/gphotos-sync folder, followed by path to where the tool should download all your Google Photos. For example, to download all Google Photos to the ~/gphotos-sync folder, use:

cd gphotos-sync
pipenv run gphotos-sync ~/gphotos-sync

The first time you run gphotos-sync, you need to authorize it with your Google (Photos) account, and a link will be shown in the terminal.

You'll need to copy the link shown in the terminal, and paste it in a web browser. It will show page that says "This app isn't verified by Google yet". This is normal, since the app is using your API key, and you didn't submit it to Google for verification. When on this screen, click Advanced, then click Go to Your_Gogle_Cloud_Project_Mame (unsafe). Click Allow when prompted, then copy the code shown by the Google OAuth page, paste it back in the terminal, and press Enter.

Run the same command (pipenv run gphotos-sync ~/gphotos-sync in the gphotos-sync folder in my example) each time you want to update the local backup of your Google Photos. It's worth noting that you'll need to wait a bit after uploading a new photo to Google Photos (e.g. using the web interface or from your phone), as it won't be available immediately for download / backup.

Refer to the application's help (pipenv run gphotos-sync --help) for advanced usage and more options.