---
id: gspread-pandas
version: "4.2.1"
license: BSD
license_treatment: permissive
maintenance: active
---

# gspread-pandas — A package to easily open an instance of a Google spreadsheet and interact with worksheets through Pandas DataFrames.

License: permissive · Maintenance: active · Downloads: 355.2K/mo

## What it is and what it does

gspread-pandas wraps gspread and pandas to simplify bidirectional data exchange with Google Sheets. It reads spreadsheets into DataFrames and writes DataFrames back to sheets, automatically handling headers, multi-level indexes, merged cells, and frozen rows. The package targets data analysts and scientists but works for anyone automating workflows between Google Sheets and Python.

Key features include automatic type inference (convert_types), layout detection for sheets with titles or blank rows (detect_layout), and intelligent append operations that match DataFrame columns to existing sheet headers by name rather than position. Optional AI-powered matching via OpenAI-compatible endpoints can handle column renames and stacked headers when configured. The package handles token refresh, retries on quota limits, and supports both OAuth and Service Account authentication.

Use it for:

- Extract data from a messy Google Sheet into a pandas DataFrame for analysis, with automatic type conversion and layout detection.
- Push analysis results from a Jupyter notebook back to a Google Sheet, preserving headers and matching columns by name.
- Automate periodic data imports from Google Sheets into a headless Python script for ETL or reporting workflows.
- Append new rows to an existing Google Sheet from a DataFrame, automatically aligning columns to the sheet's current headers.
- Handle spreadsheets with multi-level headers or merged cells by leveraging built-in support for complex layouts.

## Worth the install?

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

Bridges Google Sheets and pandas DataFrames, letting you read spreadsheets into DataFrames and write DataFrames back to sheets with automatic header handling, type inference, and layout detection.

Yes. The package is actively maintained (last commit 2026-08-13), has low install friction, no known vulnerabilities, and solves a real pain point—bridging Google Sheets and pandas without boilerplate. It supports Python 3.9+, carries a permissive BSD license, and is in production-stable status. Install it if you regularly move data between Google Sheets and pandas.

## Install

pip install gspread-pandas
uv add gspread-pandas
poetry add gspread-pandas

## Installing gspread-pandas

Before you install: Low friction: pure Python wheel with five straightforward runtime dependencies (gspread, pandas, decorator, google-auth, google-auth-oauthlib). Actively maintained—last commit 2026-08-13, 412 repository stars, production-stable classifier.

License in practice: BSD permissive license allows commercial and private use with minimal restrictions, making it suitable for both open and closed projects.

Quickstart:

pip install gspread-pandas

from gspread_pandas import Spread
import pandas as pd

spread = Spread('spreadsheet_name')
df = spread.sheet_to_df()
spread.df_to_sheet(df, replace=True)

Requires Python 3.9+, gspread 6, and pandas 2 or 3. Google client credentials (OAuth or Service Account) must be configured at ~/.config/gspread_pandas/google_secret.json or via environment variables before use.

Verify before relying:

- Whether the optional AI-powered column matching (via GSPREAD_PANDAS_AI_API_KEY) incurs costs or requires external API subscriptions.
- Performance characteristics when handling very large datasets or high-frequency API calls against Google Sheets quota limits.
- Actual monthly download volume and user base size.

## Package facts

- License: BSD (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 355.2K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

google sheets pandas integration, read write google spreadsheets dataframe, automate google sheets with python, gspread wrapper pandas, spreadsheet data extraction python, google drive sheets api wrapper, pandas dataframe to google sheets, google-sheets, dataframe-io, spreadsheet-automation

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