Registry / gcp / gspread

gspread

JSON →
library6.2.1pypypi✓ verified 24d ago

gspread is a Python API for Google Sheets, providing a simple interface to interact with spreadsheets. It supports Google Sheets API v4 and offers features like opening spreadsheets by title, key or URL, reading, writing, and formatting cell ranges, sharing, access control, and batching updates. It is currently at version 6.2.1 and is actively maintained with frequent minor and patch releases.

pip install gspread
INSTALL
IMPORT
SIG · GSPREAD
G
gspread
gcppythonv6.2.1
Install
3.7s avg
Import
1094ms
Disk
44MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v6.2.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 1.130s · 45.4MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 3.7s · import 1.058s · 46MB
44MB installed
● package 44MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

gspread
import gspread
Main library import for accessing the Google Sheets API.
gspread.service_account
import gspread gc = gspread.service_account()
gc = gspread.authorize(credentials)
The `service_account()` method is the modern and recommended way for bot/script authentication using a service account JSON key file. `authorize()` is for OAuth2 credentials via `google.auth.credentials.Credentials` objects.
gspread.oauth
import gspread gc = gspread.oauth()
Used for end-user authentication, often involving an interactive browser flow.
gspread.api_key
import gspread gc = gspread.api_key('YOUR_API_KEY')
Authenticates using an API key, suitable for accessing public spreadsheets only.
gspread.exceptions.APIError
from gspread.exceptions import APIError
Catches API-specific errors (e.g., rate limits, invalid requests) from the Google Sheets API.

This quickstart demonstrates how to authenticate with gspread using a service account, open a spreadsheet, read a cell, and update cells. Ensure you have enabled the Google Drive API and Google Sheets API in your Google Cloud project and shared your spreadsheet with the service account's email. The example uses an environment variable for the keyfile path for better security and flexibility.

import gspread import os # Ensure your service account key file path is set as an environment variable # or replace with the actual path. # For example: export GSPREAD_SERVICE_ACCOUNT_KEYFILE="./path/to/your/service_account.json" SERVICE_ACCOUNT_KEYFILE = os.environ.get( 'GSPREAD_SERVICE_ACCOUNT_KEYFILE', './path/to/your/service_account.json' # Placeholder, replace or use env var ) try: # Authenticate using a service account # Make sure to share your Google Sheet with the service account email address. gc = gspread.service_account(filename=SERVICE_ACCOUNT_KEYFILE) # Open a spreadsheet by its title spreadsheet_title = "My Test Spreadsheet" sh = gc.open(spreadsheet_title) # Select the first worksheet wks = sh.sheet1 print(f"Successfully opened spreadsheet: {sh.title}") print(f"First worksheet title: {wks.title}") # Read a single cell value cell_a1 = wks.acell('A1').value print(f"Value in A1: {cell_a1}") # Update a single cell wks.update_acell('B1', 'Hello gspread!') print("Updated cell B1.") # Update a range of cells (using v6 syntax with 2D array and named args) data_to_write = [['Name', 'Age'], ['Alice', 30], ['Bob', 24]] wks.update(values=data_to_write, range_name='A3') print("Updated range A3:B5.") # Get all values from the worksheet as a list of lists all_values = wks.get_all_values() print("\nAll values in the worksheet:") for row in all_values: print(row) except FileNotFoundError: print(f"Error: Service account key file not found at {SERVICE_ACCOUNT_KEYFILE}. ") print("Please ensure the file exists and the path is correct.") except gspread.exceptions.SpreadsheetNotFound: print(f"Error: Spreadsheet '{spreadsheet_title}' not found or not shared with the service account.") print("Ensure the spreadsheet name is correct and shared with the client_email from your service account JSON.") except gspread.exceptions.APIError as e: print(f"Google Sheets API Error: {e}") print("This might be a rate limit issue or incorrect API permissions.") except Exception as e: print(f"An unexpected error occurred: {e}")
Debug
Known issues
breakingPython 3.7 End-of-Life: gspread v6+ officially drops support for Python 3.7. Your project must use Python 3.8 or newer.
fix
Upgrade your Python environment to 3.8 or a later version.
affects: 6.0.0 and later
breakingWorksheet.update() arguments swapped and value format changed. The `values` and `range_name` arguments are swapped. Additionally, `values` must now be a 2D array (list of lists), not a simple list.
fix
Either swap the arguments (`worksheet.update(values, range_name)`) or, preferably, use named arguments (`worksheet.update(values=..., range_name=...)`) for clarity and forward compatibility. Ensure `values` is always a list of lists.
affects: 6.0.0 and later
breakingWorksheet.get_records() method removed. This method is no longer available in v6.
fix
Use `worksheet.get_all_records()` to retrieve all records or fetch specific ranges with `worksheet.get()` and process them using `gspread.utils.to_records(header, cells)` if partial records are needed.
affects: 6.0.0 and later
breakingColor representation for formatting changed from dictionary to hexadecimal strings.
fix
Convert color dictionaries to hexadecimal strings (e.g., `{'red': 1, 'green': 0.5, 'blue': 1}` to `"#FF7FFF"`). A utility function `gspread.utils.convert_colors_to_hex_value()` is available for compatibility.
affects: 6.0.0 and later
gotchaSpreadsheetNotFound error (or similar access issues) when using a Service Account.
fix
You *must* share the target Google Sheet with the `client_email` address found in your service account's JSON key file. Treat it like sharing with any other Google user.
affects: All versions
gotchaGoogle Sheets API rate limits can lead to `gspread.exceptions.APIError: 429 RESOURCE_EXHAUSTED`.
fix
The Sheets API has limits (e.g., 100 requests/100 seconds per project, 60 requests/60 seconds per user). Minimize API calls by using batch operations (`update()`, `batch_update()`, `get_all_values()`, `batch_get()`) instead of individual cell/row operations in loops. Consider using `gspread.http_client.BackOffHTTPClient` for automatic retry with exponential back-off.
affects: All versions
gotchaOAuth Client ID authentication sometimes results in `google.auth.exceptions.RefreshError: invalid_grant: Token has been expired or revoked.`
fix
This usually means the `authorized_user.json` credentials have expired. Delete the `authorized_user.json` file (located in `~/.config/gspread/` on Linux/macOS or `%APPDATA%\gspread\` on Windows) and re-run your code to initiate a new authentication flow.
affects: All versions using OAuth Client ID
gotchaService account key file not found. This error indicates that the gspread client could not locate the specified service account JSON key file, preventing authentication.
fix
Ensure that the path to your service account JSON key file (e.g., `./path/to/your/service_account.json`) is correct and that the file exists at that location. Double-check file permissions if the path is correct but the file is inaccessible by the running process. The path is typically provided during client authorization (e.g., `gspread.service_account(filename='path/to/key.json')`).
affects: All versions
gotchaService account key file not found at the specified path during initialization.
fix
Verify that the JSON key file for your service account exists at the path you are providing (e.g., to `gspread.service_account(filename='path/to/key.json')`) or that the `GSPREAD_SERVICE_ACCOUNT_PATH` environment variable points to a valid file. Double-check the filename and directory path for typos and correct permissions.
affects: All versions
Errors
Common errors & fixes
google.auth.exceptions.RefreshError: ('invalid_grant: Token has been expired or revoked.', {'error': 'invalid_grant', 'error_description': 'Token has been expired or revoked.'})
This error typically means your OAuth 2.0 client credentials (specifically the refresh token) have expired, been revoked, or are otherwise invalid, often due to an outdated `authorized_user.json` file or the user revoking access from their Google account.
fix
Delete the `authorized_user.json` file (on Windows: `%APPDATA%\gspread\`, on other systems: `~/.config/gspread/credentials.json`) and re-run your code to initiate a new authentication flow.
gspread.exceptions.APIError: {'code': 403, 'message': 'The caller does not have permission', 'status': 'PERMISSION_DENIED'}
This error occurs when the service account or authenticated user lacks the necessary permissions (e.g., editor access) to interact with the target Google Sheet or Drive API.
fix
Share the Google Sheet directly with the service account's email address (found in your service account JSON key file) and grant it editor permissions, or ensure the authenticated user has sufficient access to the sheet.
gspread.exceptions.SpreadsheetNotFound: {'code': 404, 'message': 'Requested entity was not found.'}
The specified Google Sheet could not be found, often due to an incorrect spreadsheet title, key, or URL, or because the service account/user does not have access to the spreadsheet.
fix
Double-check the spreadsheet title, key, or URL for typos, and ensure the Google Sheet is shared with the service account's email address.
AttributeError: 'Worksheet' object has no attribute 'update'
This error usually indicates that the `gspread` library version is outdated, and the `update()` method (or similar methods like `insert_rows()`) that you are trying to use was not available in that older version.
fix
Upgrade `gspread` to the latest version using `pip install --upgrade gspread` to access the newer API methods.
Upgrade
Version history
6.2.1latest on PyPI · released May 14, 2025
Audit
Dependencies
pythonrequiredRequires Python >=3.8.
google-authrequiredUsed for various authentication methods (service account, OAuth).
requestsrequiredUsed for HTTP communication with the Google Sheets API.
Agent activity
35 hits · last 30 days
node
30
OpenAI (training)
1
Resources
gspread — pip install gspread · libregistry