Welcome to gspread-dataframe’s documentation!


If you have pandas (>= 0.14.0) installed, the gspread_dataframe module offers get_as_dataframe and set_with_dataframe functions to return a worksheet’s contents as a DataFrame object, or set a worksheet’s contents using a DataFrame.

import pandas as pd
from gspread_dataframe import get_as_dataframe, set_with_dataframe

worksheet = some_worksheet_obtained_from_gspread_client

df = pd.DataFrame.from_records([{'a': i, 'b': i * 2} for i in range(100)])
set_with_dataframe(worksheet, df)

df2 = get_as_dataframe(worksheet)

The get_as_dataframe function supports the keyword arguments that are supported by your Pandas version’s text parsing readers, such as pandas.read_csv. Consult your Pandas documentation for a full list of options; since the 'python' engine in Pandas is used for parsing, only options supported by that engine are acceptable:

import pandas as pd
from gspread_dataframe import get_as_dataframe

worksheet = some_worksheet_obtained_from_gspread_client

df = get_as_dataframe(worksheet, parse_dates=True, usecols=[0,2], skiprows=1, header=None)



  • Python 2.6+ and Python 3.2+
  • Pandas >= 0.14.0

From PyPI

pip install gspread-dataframe

From GitHub

git clone https://github.com/robin900/gspread-dataframe.git
cd gspread-dataframe
python setup.py install

Module Documentation - Version 2.0


This module contains functions to retrieve a gspread worksheet as a pandas.DataFrame, and to set the contents of a worksheet using a pandas.DataFrame. To use these functions, have Pandas 0.14.0 or greater installed.

gspread_dataframe.get_as_dataframe(worksheet, evaluate_formulas=False, **options)

Returns the worksheet contents as a DataFrame.

  • worksheet – the worksheet.
  • evaluate_formulas – if True, get the value of a cell after formula evaluation; otherwise get the formula itself if present. Defaults to False.
  • **options – all the options for pandas.io.parsers.TextParser, according to the version of pandas that is installed. (Note: TextParser supports only the ‘python’ parser engine.)


gspread_dataframe.set_with_dataframe(worksheet, dataframe, row=1, col=1, include_index=False, include_column_header=True, resize=False, allow_formulas=True)

Sets the values of a given DataFrame, anchoring its upper-left corner at (row, col). (Default is row 1, column 1.)

  • worksheet – the gspread worksheet to set with content of DataFrame.
  • dataframe – the DataFrame.
  • include_index – if True, include the DataFrame’s index as an additional column. Defaults to False.
  • include_column_header – if True, add a header row before data with column names. (If include_index is True, the index’s name will be used as its column’s header.) Defaults to True.
  • resize – if True, changes the worksheet’s size to match the shape of the provided DataFrame. If False, worksheet will only be resized as necessary to contain the DataFrame contents. Defaults to False.
  • allow_formulas – if True, interprets =foo as a formula in cell values; otherwise all text beginning with = is escaped to avoid its interpretation as a formula. Defaults to True.

Indices and tables