{"id":2691,"library":"pygsheets","title":"Pygsheets: Google Spreadsheets Python API v4","description":"Pygsheets is a simple, intuitive Python library that provides an interface to the Google Sheets API v4. It enables programmatic interaction with Google Spreadsheets, allowing users to create, open, edit, and share spreadsheets, as well as manage worksheets, cells, and ranges. The library supports advanced features like conditional formatting, data validation, and batch operations. The current version is 2.0.6, and it maintains an active development cycle with regular updates and bug fixes.","status":"active","version":"2.0.6","language":"en","source_language":"en","source_url":"https://github.com/nithinmurali/pygsheets","tags":["google-sheets","spreadsheet","api","data-manipulation","automation"],"install":[{"cmd":"pip install pygsheets","lang":"bash","label":"Install stable version from PyPI"}],"dependencies":[{"reason":"Required for DataFrame integration (e.g., set_dataframe, get_as_df).","package":"pandas","optional":true}],"imports":[{"symbol":"pygsheets","correct":"import pygsheets"}],"quickstart":{"code":"import pygsheets\nimport os\n\n# Ensure your service account JSON key file is present and its path is in an environment variable\n# Instructions to get one: https://pygsheets.readthedocs.io/en/latest/authorization.html#service-account\nservice_file_path = os.environ.get('PYGSHEETS_SERVICE_ACCOUNT_FILE', 'path/to/your/service_account.json')\n\nif not os.path.exists(service_file_path) or service_file_path == 'path/to/your/service_account.json':\n    print(f\"Warning: Service account file not found at '{service_file_path}'. Please set PYGSHEETS_SERVICE_ACCOUNT_FILE environment variable or update the path.\")\n    print(\"Cannot run quickstart without valid service account credentials.\")\nelse:\n    try:\n        # Authorize with service account credentials\n        gc = pygsheets.authorize(service_account_file=service_file_path)\n\n        # Open a spreadsheet by name or create it if it doesn't exist\n        spreadsheet_name = \"My Test Spreadsheet\"\n        try:\n            sh = gc.open(spreadsheet_name)\n            print(f\"Opened existing spreadsheet: {spreadsheet_name}\")\n        except pygsheets.exceptions.SpreadsheetNotFound:\n            sh = gc.create(spreadsheet_name)\n            # Share with your Google account if you want to see it in your Drive\n            # sh.share('your-email@example.com', role='writer', type='user')\n            print(f\"Created new spreadsheet: {spreadsheet_name}\")\n\n        # Select the first worksheet\n        wks = sh[0]\n\n        # Update a cell\n        wks.update_value('A1', 'Hello from pygsheets!')\n        print(f\"Updated cell A1 in '{spreadsheet_name}' with 'Hello from pygsheets!'\")\n\n        # Get a value\n        cell_value = wks.get_value('A1')\n        print(f\"Value in A1: {cell_value}\")\n\n        # Update a range of values\n        data = [[1, 2, 3], [4, 5, 6]]\n        wks.update_values('B2', data)\n        print(f\"Updated range B2:D3 with: {data}\")\n\n    except Exception as e:\n        print(f\"An error occurred: {e}\")","lang":"python","description":"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."},"warnings":[{"fix":"Old 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.","message":"Version 2.0.0 introduced significant breaking changes, including function renames and `authorize()` parameter changes.","severity":"breaking","affected_versions":"2.0.0 and later"},{"fix":"While 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.","message":"In version 2.0.3, the internal handling of cell addressing was fundamentally changed, introducing `Address` and `GridRange` objects.","severity":"breaking","affected_versions":"2.0.3 and later"},{"fix":"If 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.","message":"The default behavior of `get_as_df` changed in version 2.0.5.","severity":"breaking","affected_versions":"2.0.5 and later"},{"fix":"You 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.","message":"Authorization requires careful setup of a Google Cloud Project.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If 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.","message":"When working with `Cell` objects, properties other than `value` are not fetched by default.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Use the `batch_mode` context manager on the `Client` object for efficient batching of updates instead of manually linking and unlinking worksheets.","message":"The `link()` and `unlink()` methods on `Worksheet` objects are deprecated.","severity":"deprecated","affected_versions":"Versions with batch_mode support (e.g., 2.0.4+)"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}