A simple, intuitive python library to access google spreadsheets through the Google Sheets API v4. So for example if you have few csv files which you want to export to google sheets and then plot some graphs based on the data. You can use this library to automate that.


  • Google Sheets API v4 support.
  • Limited Google Drive API v3 support.
  • Open and create spreadsheets by title.
  • Add or remove permissions from you spreadsheets.
  • Simple calls to get a row, column or defined range of values.
  • Change the formatting properties of a cell.
  • Supports named ranges & protected ranges.
  • Queue up requests in batch mode and then process them in one go.


New version 2.0.0 released. Please see changelog to migrate from 1.x.

Small Example

First example - Share a numpy array with a friend:

import pygsheets

client = pygsheets.authorize()

# Open the spreadsheet and the first sheet.
sh ='spreadsheet-title')
wks = sh.sheet1

# Update a single cell.
wks.update_value('A1', "Numbers on Stuff")

# Update the worksheet with the numpy array values. Beginning at cell 'A2'.
wks.update_values('A2', my_numpy_array.to_list())

# Share the sheet with your friend. (read access only)
# sharing with write access
sh.share('', role='writer')

Second example - Store some data and change cell formatting:

# open a worksheet as in the first example.

header = wks.cell('A1')
header.value = 'Names'
header.text_format['bold'] = True # make the header bold

# The same can be achieved in one line
wks.cell('B1').set_text_format('bold', True).value = 'heights'

# set the names

# set the heights
heights = wks.range('B2:B5', returnas='range')  # get the range = "heights"  # name the range
heights.update_values([[50],[60],[67],[66]]) # update the values
wks.update_value('B6','=average(heights)') # set get the avg value


Install recent:

pip install

Install stable:

pip install pygsheets


The Client is used to create and access spreadsheets. The property drive exposes some Google Drive API functionality and the sheet property exposes used Google Sheets API functionality.

A Google Spreadsheet is represented by the Spreadsheet class. Each spreadsheet contains one or more Worksheet. The data inside of a worksheet can be accessed as plain values or inside of a Cell object. The cell has properties and attributes to change formatting, formulas and more. To work with several cells at once a DataRange can be used.

Authors and License

The pygsheets package is written by Nithin M and is inspired by gspread.

Licensed under the MIT-License.

Feel free to improve this package and send a pull request to GitHub.


Indices and tables