Skip to content
This repository

Google Spreadsheets Python API

branch: master

Google Spreadsheets Python API


Manage your spreadsheets with gspread in Python.


  • Open a spreadsheet by its title or url.
  • Extract range, entire row or column values.
  • Independent of Google Data Python client library.
  • Python 3 support.


Basic Usage

import gspread

# Login with your Google account
gc = gspread.login('', 'password')

# Open a worksheet from spreadsheet with one shot
wks ="Where is the money Lebowski?").sheet1

wks.update_acell('B2', "it's down there somewhere, let me take another look.")

# Fetch a cell range
cell_list = wks.range('A1:B7')

More Examples

Opening a spreadsheet

# You can open a spreadsheet by its title as it appears in Google Docs
sh ="My poor gym results") # <-- Look ma, no keys!

# If you want to be specific, use a key (which can be extracted from
# the spreadsheet's url)
sht1 = gc.open_by_key('0BmgG6nO_6dprdS1MN3d3MkdPa142WFRrdnRRUWl1UFE')

# Or, if you feel really lazy to extract that key, paste the entire url
sht2 = gc.open_by_url('')

Selecting a worksheet

# Select worksheet by index. Worksheet indexes start from zero
worksheet = sh.get_worksheet(0)

# By title
worksheet = sh.worksheet("January")

# Most common case: Sheet1
worksheet = sh.sheet1

# Get a list of all worksheets
worksheet_list = sh.worksheets()

Creating a worksheet

worksheet = sh.add_worksheet(title="A worksheet", rows="100", cols="20")

Deleting a worksheet


Getting a cell value

# With label
val = worksheet.acell('B1').value

# With coords
val = worksheet.cell(1, 2).value

Getting all values from a row or a column

# Get all values from the first row
values_list = worksheet.row_values(1)

# Get all values from the first column
values_list = worksheet.col_values(1)

Getting all values from a worksheet as a list of lists

list_of_lists = worksheet.get_all_values()

Finding a cell

# Find a cell with exact string value
cell = worksheet.find("Dough")

print("Found something at R%sC%s" % (cell.row, cell.col))

# Find a cell matching a regular expression
amount_re = re.compile(r'(Big|Enormous) dough')
cell = worksheet.find(amount_re)

Finding all matched cells

# Find all cells with string value
cell_list = worksheet.findall("Rug store")

# Find all cells with regexp
criteria_re = re.compile(r'(Small|Room-tiering) rug')
cell_list = worksheet.findall(criteria_re)

Cell object

Each cell has a value and coordinates properties.

value = cell.value
row_number = cell.row
column_number = cell.col

Updating cells

worksheet.update_acell('B1', 'Bingo!')

# Or
worksheet.update_cell(1, 2, 'Bingo!')

# Select a range
cell_list = worksheet.range('A1:C7')

for cell in cell_list:
    cell.value = 'O_o'

# Update in batch

Two Factor Authorization

In case your Google Account protected with Two Factor Authorization, you have to create an application-specific password and use your email to login as usual.

Otherwise you will get an AuthenticationError: Unable to authenticate. 403 code when trying to login.


Python 2.6+ or Python 3+


From GitHub

git clone
cd gspread
python install

From PyPI

pip install gspread

If you're on easy_install, it's:

easy_install gspread


API Reference


  1. Go to Google Drive and create an empty spreadsheet you will use for testing.
  2. Create a configuration file from config dummy:

    cp tests/tests.config.example tests/tests.config
  3. Open tests.config with your favorite editor and fill up config parameters with your testing spreadsheet's info.

  4. Install Nose.
  5. Run tests:


Suggestions & Code Contribution


Please report bugs and suggest features via GitHub Issues.

Something went wrong with that request. Please try again.