---
id: gspread-dataframe
version: "4.0.0"
license: MIT
license_treatment: permissive
maintenance: aging
---

# gspread-dataframe — Read/write gspread worksheets using pandas DataFrames

License: permissive · Maintenance: aging · Downloads: 4.0M/mo

## What it is and what it does

gspread-dataframe bridges pandas DataFrames and Google Sheets by wrapping gspread. It provides two main functions: get_as_dataframe() reads a worksheet into a DataFrame with support for pandas read_csv options like parse_dates and usecols, and set_with_dataframe() writes a DataFrame back to a worksheet. Version 4.0.0 added drop_empty_rows and drop_empty_columns parameters to automatically trim unused cells from the default Google Sheet grid.

The package is designed for workflows where you need to move data between spreadsheets and Python analysis pipelines. It depends on gspread (>=3.0.0), pandas (>=0.24.0), and six, making it a thin adapter layer. It integrates optionally with gspread-formatting for post-write cell formatting.

Use it for:

- Export analysis results from a pandas pipeline directly to a shared Google Sheet for stakeholder review.
- Read data from a Google Sheet into a DataFrame for data cleaning and statistical analysis in Python.
- Automate periodic data synchronization between a Google Sheet and a local pandas workflow.
- Build a data collection tool where users input data in Google Sheets and Python processes it automatically.
- Trim empty rows and columns from a Google Sheet after writing a DataFrame using drop_empty_rows and drop_empty_columns.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Converts between Google Sheets worksheets and pandas DataFrames, allowing bidirectional data transfer via the gspread library.

Yes, if you need straightforward pandas-to-Google-Sheets integration and can tolerate aging maintenance. The package is Production/Stable, has no known vulnerabilities, and handles the core use case well. However, verify compatibility with your specific gspread and pandas versions, and be aware that the last release was 793 days ago—consider this if you need active bug fixes or new features.

## Install

pip install gspread-dataframe
uv add gspread-dataframe
poetry add gspread-dataframe

## Installing gspread-dataframe

Before you install: Low install friction with a pure-Python wheel distribution. Maintenance is aging—last release was 793 days ago, though the repository remains active with a recent commit and no archived status.

License in practice: MIT license permits commercial and private use with minimal restrictions; you may use, modify, and distribute the package freely provided you retain the license notice.

Quickstart:

pip install gspread-dataframe

import pandas as pd
from gspread_dataframe import get_as_dataframe, set_with_dataframe

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)

Requires a worksheet object obtained from gspread client and Google Sheets API credentials configured.

Verify before relying:

- Whether the package works reliably with current versions of gspread and pandas beyond the stated minimum requirements.
- Performance characteristics when working with large DataFrames or worksheets.
- Actual Python 2.7 support given the aging maintenance status and modern ecosystem shifts.

## Package facts

- License: MIT (permissive)
- Python support: unspecified
- Install friction: low
- Maintenance: aging
- Downloads: 4.0M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

google sheets pandas dataframe, read google spreadsheet dataframe, write dataframe to google sheets, gspread dataframe integration, sync pandas with google sheets, spreadsheet to dataframe conversion, google-sheets, data-sync, spreadsheet-automation

[View on SkillFed](https://skillfed.io/packages/gspread-dataframe) · [View on PyPI](https://pypi.org/project/gspread-dataframe/)