Install & Compatibility
Where this runs
tested against v2.0.6 · 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.474s · 153.8MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 5.4s · import 1.372s · 155MB
153MB installed
● package 153MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
pygsheets
✓ import pygsheets
This quickstart demonstrates how to authorize `pygsheets` using a service account, open or create a Google Sheet, and perform basic operations like updating and retrieving cell values. Remember to set up a Google Cloud Project, enable the Google Sheets API and Google Drive API, create a service account, and download its JSON key file. The path to this file should be provided via the `PYGSHEETS_SERVICE_ACCOUNT_FILE` environment variable for secure credential handling.
import pygsheets
import os
# Ensure your service account JSON key file is present and its path is in an environment variable
# Instructions to get one: https://pygsheets.readthedocs.io/en/latest/authorization.html#service-account
service_file_path = os.environ.get('PYGSHEETS_SERVICE_ACCOUNT_FILE', 'path/to/your/service_account.json')
if not os.path.exists(service_file_path) or service_file_path == 'path/to/your/service_account.json':
print(f"Warning: Service account file not found at '{service_file_path}'. Please set PYGSHEETS_SERVICE_ACCOUNT_FILE environment variable or update the path.")
print("Cannot run quickstart without valid service account credentials.")
else:
try:
# Authorize with service account credentials
gc = pygsheets.authorize(service_account_file=service_file_path)
# Open a spreadsheet by name or create it if it doesn't exist
spreadsheet_name = "My Test Spreadsheet"
try:
sh = gc.open(spreadsheet_name)
print(f"Opened existing spreadsheet: {spreadsheet_name}")
except pygsheets.exceptions.SpreadsheetNotFound:
sh = gc.create(spreadsheet_name)
# Share with your Google account if you want to see it in your Drive
# sh.share('your-email@example.com', role='writer', type='user')
print(f"Created new spreadsheet: {spreadsheet_name}")
# Select the first worksheet
wks = sh[0]
# Update a cell
wks.update_value('A1', 'Hello from pygsheets!')
print(f"Updated cell A1 in '{spreadsheet_name}' with 'Hello from pygsheets!'")
# Get a value
cell_value = wks.get_value('A1')
print(f"Value in A1: {cell_value}")
# Update a range of values
data = [[1, 2, 3], [4, 5, 6]]
wks.update_values('B2', data)
print(f"Updated range B2:D3 with: {data}")
except Exception as e:
print(f"An error occurred: {e}")
Debug
Known issues
breakingVersion 2.0.0 introduced significant breaking changes, including function renames and `authorize()` parameter changes.fixOld functions like `update_cell()`, `update_cells()`, and `update_cells_prop()` were renamed to `update_value()`, `update_values()`, and `update_cells()` respectively. Parameters for `authorize()` like `outh_file` changed to `client_secret` and `service_file` to `service_account_file`. Review the 2.0.0 release notes and documentation for a full migration guide.
affects: 2.0.0 and later
breakingIn version 2.0.3, the internal handling of cell addressing was fundamentally changed, introducing `Address` and `GridRange` objects.fixWhile many high-level functions might still accept string notations (e.g., 'A1'), direct manipulation or advanced range operations might require adapting to the new `Address` and `GridRange` objects. Consult the documentation for the correct usage of addressing.
affects: 2.0.3 and later
breakingThe default behavior of `get_as_df` changed in version 2.0.5.fixIf you relied on the previous default behavior of `get_as_df`, you might need to adjust parameters like `include_tailing_empty` or `include_tailing_empty_rows` to match the desired output.
affects: 2.0.5 and later
gotchaAuthorization requires careful setup of a Google Cloud Project.fixYou must enable the Google Sheets API and Google Drive API, create a service account, and download its JSON key file. Share your spreadsheet with the service account's email address (found in the JSON key file) to grant it access.
affects: All versions
gotchaWhen working with `Cell` objects, properties other than `value` are not fetched by default.fixIf you need to access or modify cell properties (like format, color, notes), you must explicitly call `cell.fetch()` on the `Cell` object to retrieve its full properties from the spreadsheet, or ensure the cell was obtained with a fetch operation that included properties.
affects: All versions
deprecatedThe `link()` and `unlink()` methods on `Worksheet` objects are deprecated.fixUse the `batch_mode` context manager on the `Client` object for efficient batching of updates instead of manually linking and unlinking worksheets.
affects: Versions with batch_mode support (e.g., 2.0.4+)
Errors
Common errors & fixes
google.auth.exceptions.RefreshError: ('invalid_grant: Token has been expired or revoked.',
The authentication token used by pygsheets to access your Google account has expired or been revoked, often due to project status, inactivity, or explicit revocation.
fixDelete the old token file (e.g., `sheets.googleapis.com-python.json` or `token.pickle`) and re-run `pygsheets.authorize()` to re-authenticate; set your Google Cloud project's OAuth consent screen to 'Production' status for persistent applications.
IOError: [Errno 2] Client secret file does not exist.: 'client_secret.json'
The `client_secret.json` (or `credentials.json`) file, required for OAuth authentication, is not found in the expected location by pygsheets.
fixEnsure `client_secret.json` is in the same directory as your script or provide its full absolute path to `pygsheets.authorize(client_secret='path/to/client_secret.json')`.
pygsheets.exceptions.SpreadsheetNotFound: Could not find a spreadsheet with title 'Your Spreadsheet Name'
The specified Google Sheet cannot be found, either due to a typo in its name/key/URL, or the authenticating service/user account lacks permission to access it.
fixDouble-check the spreadsheet title, key, or URL for accuracy, and if using a service account, share the Google Sheet with the service account's email address and grant editor permissions.
pygsheets.exceptions.CellNotFound
Attempting to access a cell using an index or `find()` method that does not exist within the worksheet's current dimensions or contains the searched value.
fixVerify that row and column indices are within the worksheet's bounds or that the value exists; consider fetching all values into a local list (`wks.get_all_values()`) for safer processing or using `wks.find()` with proper error handling.
HttpError 429: Too Many Requests
The application has exceeded the Google Sheets API's usage quotas, either for unauthenticated requests or too many authenticated requests within a short timeframe.
fixImplement exponential backoff to retry requests with increasing delays, ensure proper authentication for authenticated endpoints, and consider requesting a quota increase via the Google Cloud Console if limits are consistently hit.
Upgrade
Version history
2.0.6latest on PyPI · released Nov 30, 2022
Audit
Dependencies
pandasoptionalRequired for DataFrame integration (e.g., set_dataframe, get_as_df).