Skip to main content

Archives the contents of your Google Photos library to disk

Project description


CircleCI codecov PyPI version


google-photos-archiver aims to provide a simple, fast, extensible interface to be able to back up one's Google Photos to a location of their choosing.

I've drawn inspiration from projects such as: & but wanted to cut my teeth in this domain and see what I could come up with myself.


I wanted a tool (of my own creation) which could easily provide a copy of mine and my partner's Google Photos libraries, and keep said copy up to date over time.

In reality I've mainly just needed a distraction from the vicious cycle of wake, work, Netflix, sleep, and I thought it was high time to do a little side project.


Development Pre-reqs

  • docker

... Or

Optional Reqs

Getting Started

Google Oauth Setup

These instructions will help you set up Google OAuth2 client credentials so you can start using google-photos-archiver

  • While logged into your Google account navigate to Create a New Project
  • Create one, and switch to using it with the UI dropdown
  • Navigate to APIs & Services click on + Enable APIs and services, and enable the Photos Library API
  • Navigate back to APIs & Services and click on Credentials
  • Click on + Create Credentials > OAuth client ID
  • Configure an OAuth consent screen. You can just fill out the required fields and hit Save.
    • Click Add Or Remove Scopes and manually add scope:
    • Accept remaining defaults, save through and return to Credentials
  • Click on + Create Credentials > OAuth client ID
  • Make a "Desktop App"
  • Congrats!, you now have a Client ID and Client Secret
  • Download the associated client_secret.json file and make note of its location as we'll be providing it's path to google-photos-archiver

First Run

A browser window will be opened during the initial OAuth flow. After successfully authenticating once, a refresh token will be stored for future use (See: --refresh-token-path) and will omit the need to reauthenticate.

Development Usage

$ git clone
$ poetry install
$ poetry run google-photos-archiver --help

... with Docker

Note that some more Docker volume mounting will be warranted here if you want to specify a different path to download to etc. Ref:

$ docker build . -t google-photos-archiver
$ docker run -v $PWD:/app/ google-photos-archiver  --help

General Usage

$ pip install google-photos-archiver
$ google-photos-archiver --help

Running tests

$ poetry run pytest


Specify a different download location

$ google-photos-archiver archive-media-items --download-path /Volumes/my-big-hdd/downloaded_media

Download from specific dates (with wildcard support)

$ google-photos-archiver archive-media-items --date-filter 2020/*/*,2021/8/22
$ google-photos-archiver archive-media-items --date-range-filter 2019/8/22-2020/8/22

Download Albums and their MediaItems only

$ google-photos-archiver archive-media-items --albums-only

Download Path Hierarchy

$ tree /<download_path>/downloaded_media/ | head
├── 2021
│ └── 1
│     ├── 1
│     │ └── a.jpg
│     └── 2
│         └──
├── 2020
│ ├── 1
│ │ └── 2
│ │     └── c.jpg
│ └── 2
│     └── 3
│         └── d.jpg
└── albums
    └── Album A
        └── <symlink /<download_path>/downloaded_media/2021/1/1/a.jpg >

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

google-photos-archiver-0.2.1.tar.gz (15.0 kB view hashes)

Uploaded source

Built Distribution

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page