{"id":5953,"library":"gspread-pandas","title":"gspread-pandas","description":"gspread-pandas is a Python package that simplifies interaction between Pandas DataFrames and Google Spreadsheets. It leverages the `gspread` library for underlying API communication and adds extensive functionality for handling DataFrame-specific operations, multi-level headers, merged cells, and authentication. The library is actively maintained with regular updates and releases.","status":"active","version":"3.3.0","language":"en","source_language":"en","source_url":"https://github.com/aiguofer/gspread-pandas","tags":["google-sheets","pandas","gspread","spreadsheet","data-analysis"],"install":[{"cmd":"pip install gspread-pandas","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Core dependency for Google Sheets API interaction. Version 3.0.0 dropped Python 2.7 support and required gspread>=5.0.0.","package":"gspread","optional":false},{"reason":"Fundamental for DataFrame operations.","package":"pandas","optional":false}],"imports":[{"note":"The primary class for interacting with a Google Spreadsheet via a Pandas DataFrame.","symbol":"Spread","correct":"from gspread_pandas import Spread"},{"note":"Used for managing Google API client and authentication. Often implicitly handled by `Spread`.","symbol":"Client","correct":"from gspread_pandas import Client"}],"quickstart":{"code":"import pandas as pd\nimport os\nfrom gspread_pandas import Spread\n\n# IMPORTANT: Ensure your Google client credentials (e.g., service account JSON)\n# are set up at ~/.config/gspread_pandas/google_secret.json or via environment variables.\n# See documentation for detailed authentication setup.\n\n# Replace with your actual spreadsheet name, or fetch from environment\nspreadsheet_name = os.environ.get('GSPREAD_PANDAS_SHEET_NAME', 'My Example Spreadsheet')\n\n# Create a dummy DataFrame to write to the spreadsheet\ndata = {'col1': [1, 2, 3], 'col2': ['A', 'B', 'C']}\ndf_to_write = pd.DataFrame(data)\n\ntry:\n    # Open the spreadsheet (or create if it doesn't exist and create_spread=True)\n    # By default, it looks for ~/.config/gspread_pandas/google_secret.json\n    spread = Spread(spreadsheet_name, create_spread=True)\n    \n    # Get a list of existing worksheets\n    print(f\"Worksheets in '{spreadsheet_name}': {spread.sheets}\")\n\n    # Write DataFrame to a new worksheet or an existing one\n    # Using 'overwrite=True' to clear existing data, 'sheet=' to specify sheet name\n    sheet_name = 'DataFrame Data'\n    print(f\"Writing DataFrame to sheet: '{sheet_name}'\")\n    spread.df_to_sheet(df_to_write, sheet=sheet_name, index=False, overwrite=True)\n    \n    # Read data back into a DataFrame\n    df_from_sheet = spread.sheet_to_df(sheet=sheet_name)\n    print(f\"\\nData read from '{sheet_name}':\")\n    print(df_from_sheet.head())\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n    print(\"Please ensure your Google API credentials are correctly configured and the spreadsheet exists/is accessible.\")","lang":"python","description":"This quickstart demonstrates how to authenticate, open/create a Google Spreadsheet, write a Pandas DataFrame to a specified worksheet, and then read it back. Proper authentication (e.g., setting up a service account JSON file in `~/.config/gspread_pandas/google_secret.json` and sharing your spreadsheet with the service account email) is a prerequisite for running this code."},"warnings":[{"fix":"Upgrade your Python environment to Python 3.x.","message":"Version 3.0.0 removed support for Python 2.7. Users must migrate to Python 3.x (minimum Python 3.5, though newer versions are recommended).","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Review the `gspread` changelog for versions 5.0.0 and above. Specifically, `gspread` v6 swapped arguments for `Worksheet.update` and requires `values` to be a 2D array.","message":"Version 3.0.0 upgraded the internal `gspread` dependency to version `5>=`. This might introduce breaking changes if your project relied on specific `gspread` APIs that changed between its major versions.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Remove the `raw_column_names` parameter from your function calls. Adjust your code to handle column names as per current documentation.","message":"The `raw_column_names` parameter was removed in version 3.0.2. Code using this parameter will break.","severity":"deprecated","affected_versions":">=3.0.2"},{"fix":"Use `replace=True` in `df_to_sheet` to first resize and clear the worksheet, or manually resize the sheet to `1x1` using `spread.sheet.resize(1, 1)` before calling `df_to_sheet`.","message":"When uploading large DataFrames, you might encounter Google Sheets API limits (e.g., max number of cells in a worksheet). If `df_to_sheet` adds rows/columns by default, it might exceed limits.","severity":"gotcha","affected_versions":"All"},{"fix":"Follow the detailed authentication steps in the `gspread-pandas` or `gspread` documentation to create and configure your Google Cloud project and credentials. Ensure the service account has editor access to your spreadsheets.","message":"Authentication requires setting up Google Cloud Project credentials (Service Account or OAuth Client ID) and placing the `google_secret.json` file in `~/.config/gspread_pandas/` (or `%APPDATA%\\gspread_pandas` on Windows) by default. Without this, operations will fail.","severity":"gotcha","affected_versions":"All"},{"fix":"Review DataFrame assignments and transformations. Prefer explicit copying (`.copy()`) or chained operations that return new DataFrames over methods that modify in-place if you require specific behavior. Pandas 3.0 introduced Copy-on-Write semantics, further emphasizing this.","message":"Internal `pandas` operations no longer use `inplace=True` as of version 3.2.1 to avoid `SettingWithCopyWarning`. If your code implicitly relied on previous in-place modifications (which were often ambiguous) or suppressed these warnings, behavior might change.","severity":"gotcha","affected_versions":">=3.2.1"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}