Google Photos

At a glance

Capability	Support
rclone support tier	Tier 5: Deprecated
Checksums	None
Modification times	Not kept: files show their upload time
Case-insensitive names	No
Duplicate names allowed	No
Server-side copy	No
Server-side move and rename	No
Folder move and rename	No: each file is moved in turn
Free space reporting	No
Empty folders	No: folders exist only while they hold files
Change notifications	No
Uploads of unknown size	No
Public links	No

The rclone backend for Google Photos is a specialized backend for transferring photos and videos to and from Google Photos.

NB The Google Photos API which rclone uses has quite a few limitations, so please read the limitations section carefully to make sure it is suitable for your use.

NB From March 31, 2025 rclone can only download photos it uploaded. This limitation is due to policy changes at Google. You may need to run rclone config reconnect remote: to make rclone work again after upgrading to rclone v1.70.

Setup notes

In CloudMount you add this drive from the Add drive screen, and the wizard asks for the options listed under Options. The notes below come from rclone’s setup guide.

Layout

As Google Photos is not a general purpose cloud storage system, the backend is laid out to help you navigate it.

The directories under media show different ways of categorizing the media. Each file will appear multiple times. So if you want to make a backup of your google photos you might choose to backup remote:media/by-month. (NB remote:media/by-day is rather slow at the moment so avoid for syncing.)

Note that all your photos and videos will appear somewhere under media, but they may not appear under album unless you’ve put them into albums.

/
- upload
    - file1.jpg
    - file2.jpg
    - ...
- media
    - all
        - file1.jpg
        - file2.jpg
        - ...
    - by-year
        - 2000
            - file1.jpg
            - ...
        - 2001
            - file2.jpg
            - ...
        - ...
    - by-month
        - 2000
            - 2000-01
                - file1.jpg
                - ...
            - 2000-02
                - file2.jpg
                - ...
        - ...
    - by-day
        - 2000
            - 2000-01-01
                - file1.jpg
                - ...
            - 2000-01-02
                - file2.jpg
                - ...
        - ...
- album
    - album name
    - album name/sub
- shared-album
    - album name
    - album name/sub
- feature
    - favorites
        - file1.jpg
        - file2.jpg

There are two writable parts of the tree, the upload directory and sub directories of the album directory.

The upload directory is for uploading files you don’t want to put into albums. This will be empty to start with and will contain the files you’ve uploaded for one rclone session only, becoming empty again when you restart rclone. The use case for this would be if you have a load of files you just want to once off dump into Google Photos. For repeated syncing, uploading to album will work better.

Directories within the album directory are also writeable and you may create new directories (albums) under album. If you copy files with a directory hierarchy in there then rclone will create albums with the / character in them. For example if you do

rclone copy /path/to/images remote:album/images

and the images directory contains

images
    - file1.jpg
    dir
        file2.jpg
    dir2
        dir3
            file3.jpg

Then rclone will create the following albums with the following files in

images
- file1.jpg
images/dir
- file2.jpg
images/dir2/dir3
- file3.jpg

This means that you can use the album path pretty much like a normal filesystem and it is a good target for repeated syncing.

The shared-album directory shows albums shared with you or by you. This is similar to the Sharing tab in the Google Photos web interface.

Options

Standard options

The wizard asks for these when you add the drive.

client_id

OAuth Client Id.

Creating your own is now strongly recommended. If you leave this blank rclone uses a shared client_id which is being retired and will stop working during 2026. See https://rclone.org/googlephotos/#making-your-own-client-id for how to create your own.

Type: string

client_secret

OAuth Client Secret.

Leave blank to use rclone’s shared client_id. If you created your own client_id then enter its client secret here.

Type: string

read_only

Set to make the Google Photos backend read only.

If you choose read only then rclone will only request read only access to your photos, otherwise rclone will request full access.

Type: bool · Default: false

Advanced options

The wizard shows these under Advanced options. Most drives work without changing any of them.

token

OAuth Access Token as a JSON blob.

Type: string

auth_url

Auth server URL.

Leave blank to use the provider defaults.

Type: string

token_url

Token server url.

Leave blank to use the provider defaults.

Type: string

client_credentials

Use client credentials OAuth flow.

This will use the OAUTH2 client Credentials Flow as described in RFC 6749.

Note that this option is NOT supported by all backends.

Type: bool · Default: false

read_size

Set to read the size of media items.

Normally rclone does not read the size of media items since this takes another transaction. This isn’t necessary for syncing. However rclone mount needs to know the size of files in advance of reading them, so setting this flag when using rclone mount is recommended if you want to read the media.

Type: bool · Default: false

start_year

Year limits the photos to be downloaded to those which are uploaded after the given year.

Type: int · Default: 2000

include_archived

Also view and download archived media.

By default, rclone does not request archived media. Thus, when syncing, archived media is not visible in directory listings or transferred.

Note that media in albums is always visible and synced, no matter their archive status.

With this flag, archived media are always visible in directory listings and transferred.

Without this flag, archived media will not be visible in directory listings and won’t be transferred.

Type: bool · Default: false

proxy

Use the gphotosdl proxy for downloading the full resolution images

The Google API will deliver images and video which aren’t full resolution, and/or have EXIF data missing.

However if you use the gphotosdl proxy then you can download original, unchanged images.

This runs a headless browser in the background.

Download the software from gphotosdl

First run with

gphotosdl -login

Then once you have logged into google photos close the browser window and run

gphotosdl

Then supply the parameter --gphotos-proxy "http://localhost:8282" to make rclone use the proxy.

Type: string

encoding

The encoding for the backend.

See the encoding section in the overview for more info.

Type: Encoding · Default: Slash,CrLf,InvalidUtf8,Dot

batch_mode

Upload file batching sync|async|off.

This sets the batch mode used by rclone.

This has 3 possible values

off - no batching
sync - batch uploads and check completion (default)
async - batch upload and don’t check completion

Rclone will close any outstanding batches when it exits which may make a delay on quit.

Type: string · Default: sync

batch_size

Max number of files in upload batch.

This sets the batch size of files to upload. It has to be less than 50.

By default this is 0 which means rclone will calculate the batch size depending on the setting of batch_mode.

batch_mode: async - default batch_size is 50
batch_mode: sync - default batch_size is the same as –transfers
batch_mode: off - not in use

Rclone will close any outstanding batches when it exits which may make a delay on quit.

Setting this is a great idea if you are uploading lots of small files as it will make them a lot quicker. You can use –transfers 32 to maximise throughput.

Type: int · Default: 0

batch_timeout

Max time to allow an idle upload batch before uploading.

If an upload batch is idle for more than this long then it will be uploaded.

The default for this is 0 which means rclone will choose a sensible default based on the batch_mode in use.

batch_mode: async - default batch_timeout is 10s
batch_mode: sync - default batch_timeout is 1s
batch_mode: off - not in use

Type: Duration · Default: 0s

description

Description of the remote.

Type: string

Limitations

Only images and videos can be uploaded. If you attempt to upload non videos or images or formats that Google Photos doesn’t understand, rclone will upload the file, then Google Photos will give an error when it is put turned into a media item.

Note that all media items uploaded to Google Photos through the API are stored in full resolution at “original quality” and will count towards your storage quota in your Google Account. The API does not offer a way to upload in “high quality” mode..

rclone about is not supported by the Google Photos backend. Backends without this capability cannot determine free space for an rclone mount or use policy mfs (most free space) as a member of an rclone union remote.

See List of backends that do not support rclone about See rclone about

Downloading Images

When Images are downloaded this strips EXIF location (according to the docs and my tests). This is a limitation of the Google Photos API and is covered by bug #112096115.

The current google API does not allow photos to be downloaded at original resolution. This is very important if you are, for example, relying on “Google Photos” as a backup of your photos. You will not be able to use rclone to redownload original images. You could use ‘google takeout’ to recover the original photos as a last resort

NB you can use the --gphotos-proxy flag to use a headless browser to download images in full resolution.

Downloading Videos

When videos are downloaded they are downloaded in a really compressed version of the video compared to downloading it via the Google Photos web interface. This is covered by bug #113672044.

NB you can use the --gphotos-proxy flag to use a headless browser to download images in full resolution.

Duplicates

If a file name is duplicated in a directory then rclone will add the file ID into its name. So two files called file.jpg would then appear as file {123456}.jpg and file {ABCDEF}.jpg (the actual IDs are a lot longer alas!).

If you upload the same image (with the same binary data) twice then Google Photos will deduplicate it. However it will retain the filename from the first upload which may confuse rclone. For example if you uploaded an image to upload then uploaded the same image to album/my_album the filename of the image in album/my_album will be what it was uploaded with initially, not what you uploaded it with to album. In practise this shouldn’t cause too many problems.

Modification times

The date shown of media in Google Photos is the creation date as determined by the EXIF information, or the upload date if that is not known.

This is not changeable by rclone and is not the modification date of the media on local disk. This means that rclone cannot use the dates from Google Photos for syncing purposes.

Size

The Google Photos API does not return the size of media. This means that when syncing to Google Photos, rclone can only do a file existence check.

It is possible to read the size of the media, but this needs an extra HTTP HEAD request per media item so is very slow and uses up a lot of transactions. This can be enabled with the --gphotos-read-size option or the read_size = true config parameter.

If you want to use the backend with rclone mount you may need to enable this flag (depending on your OS and application using the photos) otherwise you may not be able to read media off the mount. You’ll need to experiment to see if it works for you without the flag.

Albums

Rclone can only upload files to albums it created. This is a limitation of the Google Photos API.

Rclone can remove files it uploaded from albums it created only.

Deleting files

Rclone can remove files from albums it created, but note that the Google Photos API does not allow media to be deleted permanently so this media will still remain. See bug #109759781.

Rclone cannot delete files anywhere except under album.

Deleting albums

The Google Photos API does not support deleting albums - see bug #135714733.

Making your own client_id

When you use rclone with Google photos in its default configuration you are using rclone’s client_id. This is shared between all the rclone users.

This shared client_id is being retired and will stop working during 2026. To avoid interruption you must create and use your own client_id, so creating one is now required rather than optional. New remotes created with rclone config will warn you if you leave the client_id blank.

Please follow the steps in the google drive docs with the following differences:

At step 3, instead of enabling the “Google Drive API”, search for and enable the “Photos Library API”.
At step 5, you will need to add different scopes. Use these scopes instead of the drive ones:

https://www.googleapis.com/auth/photoslibrary.appendonly
https://www.googleapis.com/auth/photoslibrary.readonly.appcreateddata
https://www.googleapis.com/auth/photoslibrary.edit.appcreateddata