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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 1.130s · 45.4MB
glibcpy 3.10–3.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.fixUpgrade 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.fixEither 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.fixUse `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.fixConvert 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.fixYou *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`.fixThe 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.`fixThis 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.fixEnsure 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.fixVerify 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.
fixDelete 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.
fixShare 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.
fixDouble-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.
fixUpgrade `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.