Skip to main content

Unofficial Google Photos Python library

Project description


Interact with Google Photos in Python

PyPI version Documentation Status License: MIT

NOTE: Updated to Google API 2.0.0; please update this package to the new version.

Sorry for breaking some compatibility here, but Google has had some small changes under the hood, which require this update (See Issue#12).


You can use Pypi distribution (recommended method):

pip install gphotospy

Otherwise clone this repo and use the modules in gphotospy directly (not recommended).

Usage examples

This library is unofficial; most of the API is covered, however no proper test coverage has been implemented so far.

Please refer to Google's authorization guide (recommended), or see the below "Set up authorization" for a quick review on how to get Google's API keys and authorization (save it in a gphoto_oauth.json file).

from gphotospy import authorize
from gphotospy.album import Album

# Select secrets file (got through Google's API console)
CLIENT_SECRET_FILE = "gphoto_oauth.json" # Here your secret's file. See below.

# Get authorization and return a service object
service = authorize.init(CLIENT_SECRET_FILE)

# Init the album manager
album_manager = Album(service)

# Create a new album
new_album = album_manager.create('test album')

# Get the album id and share it
id_album = new_album.get("id")


Check the examples folder for more examples of use.


Check the wiki for tutorials

API Coverage

  • <input type="checkbox" checked="" disabled="" /> OAuth authorization
  • <input type="checkbox" disabled="" /> Google server upload
    • <input type="checkbox" checked="" disabled="" /> Simple uploader
    • <input type="checkbox" disabled="" /> Resumable uploader
  • <input type="checkbox" checked="" disabled="" /> Albums
    • <input type="checkbox" checked="" disabled="" /> addEnrichment
    • <input type="checkbox" checked="" disabled="" /> batchAddMediaItems
    • <input type="checkbox" checked="" disabled="" /> batchRemoveMediaItems
    • <input type="checkbox" checked="" disabled="" /> create
    • <input type="checkbox" checked="" disabled="" /> get
    • <input type="checkbox" checked="" disabled="" /> list
    • <input type="checkbox" checked="" disabled="" /> share
    • <input type="checkbox" checked="" disabled="" /> unshare
  • <input type="checkbox" disabled="" /> MediaItems
    • <input type="checkbox" checked="" disabled="" /> batchCreate
    • <input type="checkbox" disabled="" /> batchGet
    • <input type="checkbox" checked="" disabled="" /> get
    • <input type="checkbox" checked="" disabled="" /> list
    • <input type="checkbox" checked="" disabled="" /> search
  • <input type="checkbox" checked="" disabled="" /> SharedAlbums
    • <input type="checkbox" checked="" disabled="" /> get
    • <input type="checkbox" checked="" disabled="" /> join
    • <input type="checkbox" checked="" disabled="" /> leave
    • <input type="checkbox" checked="" disabled="" /> list

Test Coverage

Not yet implemented. The tests have been done "live" on my account. I'm planning to set up mock tests for this suite, just for regression purposes.


  • <input type="checkbox" checked="" disabled="" /> Docstrings
  • <input type="checkbox" checked="" disabled="" /> Examples
  • [-] Tutorials (See the wiki)
  • <input type="checkbox" checked="" disabled="" /> API docs (must be improved though)

Near future plans

These are the next steps:

  • <input type="checkbox" disabled="" /> Finish Documentation
  • <input type="checkbox" disabled="" /> Mock tests
  • <input type="checkbox" disabled="" /> Resumable Uploads
  • <input type="checkbox" disabled="" /> Objects representations
    • <input type="checkbox" checked="" disabled="" /> Media
    • <input type="checkbox" disabled="" /> Album
    • ...

Accepting ideas, so don't be shy and put them forth!

Set up authorization

Browse through Google's authorization guide

Quick recap:

Go to Google Cloud Console. Set up a new project, then on the menu select: Api & Services > Library. In the library, search for "photos", select Photo Library API and click on the ENABLE button. On the API & Services, Photo Library API select Credentials, and select the +CREDENTIALS and select in the dropdown OAuth client ID. Select the type of app to be created (for desktop application select "other") and give it a name. If you are an occasional user, you should before this thing select the authorization display (OAuth Consent Screen), and make it public (if you are not a g-Suite user $$$. THe interface prompts you already to do so, if never done before). After this, coming back to the main interface, select in the row of the OAuth 2.0 Client ID just created the download button (rightmost one). Download the .json file in the root of the project, and give it a meaningful name (because it must be used afterwards). Remember to keep all these secret files far from git pushes, so if you are committing your porject to a repository, add the downloaded file to the .gitignore.

Once run the authentication it should open a browser to authenticate. If you are creating a project for non commercial use you need not apply for review, but you have to allow it, because Google show a big message of warining. Clicking on advanced, it shows the button to allow the authorization, even though the app is not reviewed by Google (useful for tests and personal use projects). A .token file will keep the authorization for further use


Please give me some heads up if you are working on an interesting feature to add to gphotospy before a PR (well, even afterwards it's ok).

  1. Fork it (
  2. Create your feature branch (git checkout -b feature/fooBar)
  3. Commit your changes (git commit -am 'Add some fooBar')
  4. Push to the branch (git push origin feature/fooBar)
  5. Create a new Pull Request


MIT, see the LICENSE file.


  • V. 0.1.2: Added media item object representation
  • V. 0.1.1: Added documentation
  • V. 0.1.0: Fisrt usable version

About me

Too shy to talk about it (not true). This project though has been a relief during COVID lockdown.

Project details

Download files

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

Files for gphotospy, version 0.2.1
Filename, size File type Python version Upload date Hashes
Filename, size gphotospy-0.2.1-py3-none-any.whl (19.2 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size gphotospy-0.2.1.tar.gz (18.1 kB) File type Source Python version None Upload date Hashes View

Supported by

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