gspread-pandas
A package to easily open an instance of a Google spreadsheet and interact with worksheets through Pandas DataFrames.
Decision gist · record as of 2026-08-14
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.AI-flagged interpretation of the facts on this page — verify before relying
Before you install
- 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.
- Low friction: pure Python wheel with five straightforward runtime dependencies (gspread, pandas, decorator, google-auth, google-auth-oauthlib).
License · maintenance · safety
BSD (permissive) — BSD permissive license allows commercial and private use with minimal restrictions, making it suitable for both open and closed projects.
last release 2026-08-12 (2 days) · last repo commit 2026-08-13 · 412 stars
0 known vulnerabilities (OSV.dev, 2026-08-14) · 355,210 downloads/mo, #7,293 on PyPI
Alternatives
Verify before relying
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)- 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.
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 on this page. Verify before relying on it.
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
gspread-pandas on PyPI
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.
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.
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)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 the current Python release >=3.9 |
| Install friction | Low. Pure-Python wheel |
| Runtime dependencies | 5 packagesgspreadpandasdecoratorgoogle-authgoogle-auth-oauthlib |
| Maintenance | Actively maintained 2 days since the last release |
| Last repo commit | |
| First released | |
| Downloads | 355,210 / month, #7,293 on PyPI 30-day window, as of 2026-08-14 |
| Known vulnerabilities | None known OSV.dev, checked 2026-08-14 |
| Classifiers | Development Status :: 5 - Production/StableIntended Audience :: DevelopersIntended Audience :: Science/ResearchLicense :: OSI Approved :: BSD LicenseProgramming Language :: Python :: 3Programming Language :: Python :: 3.10Programming Language :: Python :: 3.11Programming Language :: Python :: 3.12Programming Language :: Python :: 3.13Programming Language :: Python :: 3.9Topic :: Office/Business :: Financial :: Spreadsheet |
Evidence: gspread_pandas-4.2.1-py3-none-any.whl
Tags
Let your AI agent find packages like this
Example. Real query, live index.
You found this page by searching. An agent finds it by wishing: SkillFed indexes 14,416 PyPI packages by what they can do, searchable in plain language.
wish › “read write google spreadsheets dataframe”
- gspread-pandasBridges Google Sheets and pandas DataFrames, letting you read…
- gspread-dataframeConverts between Google Sheets worksheets and pandas DataFrames,…
- gsheetsgsheets provides a Python wrapper around the Google Sheets API v4 to…
Give your agent the search over MCP, or paste the wish link into any chat.
More Spreadsheet packages
gspread provides a Python interface to read, write, format, and manage Google Sheets via the Google Sheets API v4, supporting operations like opening spreadsheets by title or URL, updating cell ranges, and controlling sharing permissions.
Install it if you need to read, write, or manage Google Sheets programmatically.
Streamlit transforms Python scripts into interactive web applications with minimal code, enabling rapid development of data dashboards, reports, and chat interfaces without requiring web development expertise.
Generates Microsoft Excel 97–2003 XLS spreadsheet files from Python code with no external dependencies.
Dash is a Python framework for building interactive web applications with reactive UI elements like dropdowns and graphs tied directly to analytical code, using Flask and Plotly for rendering.
Install it if you need to turn analytical Python code into interactive dashboards or data apps.
Provides elementary financial functions (IRR, NPV, PMT, and others) that were deprecated and removed from NumPy, offering a dedicated replacement for financial calculations.
However, given the aging status (no releases since 2019) and unclear compatibility with modern Python and recent numpy versions, verify that it works with your target…
Converts between Google Sheets worksheets and pandas DataFrames, allowing bidirectional data transfer via the gspread library.
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…
See also df2gspread · gsheets · pandas-read-xml · cloudsearch · gspread-formatting · gspread-asyncio · numbers-parser · pygsheets