by gphotosuploader

gphotosuploader / gphotos-uploader-cli

Command line tool to mass upload media folders to your google photos account(s) (Mac OS / Linux)

461 Stars 57 Forks Last release: 29 days ago (v1.2.0) MIT License 531 Commits 51 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

Go Report Card codebeat badge codecov GitHub release GitHub <!--- Snap Status --->

Google Photos uploader CLI

Command line tool to mass upload media folders to your Google Photos account(s).

While the official tool only supports Mac OS and Windows, this brings an uploader to Linux too. Lets you upload photos from, in theory, any OS for which you can compile a Go program.


  • Customizable configuration: via JSON-like config file.
  • Multiple Google accounts support: upload your pictures to multiple accounts.
  • Filter files with patterns: include/exclude files & folders using patterns (see documentation).
  • Resumable uploads: Uploads can be resumed, saving time and bandwidth.
  • File deletion after uploading: Clean up local files after being uploaded.
  • Track already uploaded files: uploads only new files to save bandwidth.
  • Secure: logs you into Google using OAuth (so this app doesn't have to know your password), and stores your temporary access code in your OS's secure storage (keyring/keychain).


Rate Limiting

Google Photos imposes a rate limit on all API clients. The quota limit for requests to the Library API is 10,000 requests per project per day. The quota limit for requests to access media bytes (by loading a photo or video from a base URL) is 75,000 requests per project per day.

Photo storage and quality

All media items uploaded to Google Photos using the API are stored in full resolution at original quality. They count toward the user’s storage.

Getting started


You can install the pre-compiled binary (in several different ways) or compile from source.

Here are the steps for each of them:

Install the pre-compiled binary

homebrew tap (only on macOS for now):

$ brew install gphotosuploader/tap/gphotos-uploader-cli


Download the pre-compiled binaries from the releases page and copy to the desired location.

Compiling from source

This project will maintain compatibility with the last two Go major versions published. It could work with other versions but we can't support it.

You can compile the source code in your system.

$ git clone
$ cd gphotos-uploader-cli
$ make build

Or you can use

go get
if you prefer it:
$ go get


First initialize the config file using this command:

$ gphotos-uploader-cli init

Default configuration folder is

but you can specify your own folder using
--config /my/config/dir
. Configuration is kept in the
file inside this folder.

You must review the documentation to specify your Google Photos API credentials,

. You should tune your
configuration also.


Once it's configured you can start uploading files in this way:

$ gphotos-uploader-cli push

First time run

The first time you run

, after setting your configuration (Google Photos API credentials), few manual steps are needed:
  1. You should get an output like this one:
Visit the following URL in your browser:

After completing the authorization flow, enter the authorization code here:

  1. Open a browser and point to the previous URL. Select the account where you wan to upload your files (the same you configured in the config file). You will see something like this:

Google asking for Google Photos API credentials

  1. After that, you should confirm that you trust on
    to access to your Google Photos account, click on Go to gphotos-uploader:

Google ask you to verify gphotos-upload-cli

  1. Finally Google will ask you to confirm permission Google Photos account:

Google ask permission to your Google Photos account

  1. A page with a code is shown in your browser, copy this code and go back to the terminal.

Final confirmation, all was good

  1. Paste the previous code in your terminal to complete the process.
After completing the authorization flow, enter the authorization code here: 4/4QFPtCv11dN3a-hVYhHkMryZe5g

All auth configuration is in place.


Help us make

the best tool for uploading your local pictures to Google Photos.

Reporting Issues

If you find a bug while working with

, please open an issue on GitHub and let us know what went wrong. We will try to fix it as quickly as we can.

Feedback & Feature Requests

You are more than welcome to open issues in this project to:

Contributing Code

This project is mainly written in Golang. If you want to contribute code, see Contributing guide lines for more information.


Use of this source code is governed by an MIT-style license that can be found in the LICENSE MIT file.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.