{"id":2057,"library":"gspread-dataframe","title":"gspread-dataframe","description":"gspread-dataframe (version 4.0.0) is a Python library that simplifies reading from and writing to Google Sheets using pandas DataFrames. It acts as an extension to the `gspread` library, providing convenient functions to convert worksheet data into DataFrames and vice-versa. The library is actively maintained, with a focus on seamless integration between Google Sheets and pandas.","status":"active","version":"4.0.0","language":"en","source_language":"en","source_url":"https://github.com/robin900/gspread-dataframe","tags":["gspread","pandas","google sheets","dataframe","spreadsheet","data-io"],"install":[{"cmd":"pip install gspread-dataframe","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Core library for interacting with Google Sheets.","package":"gspread","optional":false},{"reason":"Required for DataFrame operations.","package":"pandas","optional":false},{"reason":"Optional, for advanced worksheet formatting based on DataFrame data.","package":"gspread-formatting","optional":true}],"imports":[{"symbol":"get_as_dataframe","correct":"from gspread_dataframe import get_as_dataframe"},{"symbol":"set_with_dataframe","correct":"from gspread_dataframe import set_with_dataframe"}],"quickstart":{"code":"import gspread\nimport pandas as pd\nfrom gspread_dataframe import get_as_dataframe, set_with_dataframe\nimport os\n\n# --- Gspread Authentication (replace with your actual setup) ---\n# For service account authentication, ensure 'service_account.json' is in your path\n# and shared with the client_email in that file.\n# For a runnable example, we'll mock gspread client/worksheet objects.\n# In a real application, you would use:\n# gc = gspread.service_account(filename=os.environ.get('GOOGLE_APPLICATION_CREDENTIALS'))\n# spreadsheet = gc.open('Your Spreadsheet Name')\n# worksheet = spreadsheet.worksheet('Sheet1')\n\nclass MockWorksheet:\n    def __init__(self, data=None):\n        self._values = [list(row) for row in data] if data else []\n\n    def get_all_values(self):\n        return self._values\n\n    def update(self, range_name, values):\n        # Simple mock update for demonstration\n        if range_name == 'A1': # Assume A1 starts the update\n            for r_idx, row in enumerate(values):\n                if r_idx < len(self._values):\n                    for c_idx, val in enumerate(row):\n                        if c_idx < len(self._values[r_idx]):\n                            self._values[r_idx][c_idx] = val\n                        else:\n                            self._values[r_idx].append(val)\n                else:\n                    self._values.append(list(row))\n\n# Create a mock worksheet with some initial data\nmock_data = [\n    ['Name', 'Age', 'City'],\n    ['Alice', '30', 'New York'],\n    ['Bob', '24', 'London'],\n    ['Charlie', '35', 'Paris']\n]\nworksheet = MockWorksheet(mock_data)\n\n# Read worksheet into a DataFrame\ndf = get_as_dataframe(worksheet)\nprint(\"DataFrame from Worksheet:\")\nprint(df)\n\n# Modify the DataFrame\ndf['Age'] = df['Age'].astype(int) + 1\ndf['Country'] = ['USA', 'UK', 'France']\n\n# Write DataFrame back to worksheet\n# Note: resize=True will clear existing data and resize the sheet.\n# include_index=False by default.\nset_with_dataframe(worksheet, df, resize=True, include_column_header=True)\n\nprint(\"\\nUpdated Worksheet (mocked values):\")\nprint(worksheet.get_all_values())\n\n# Example of reading with pandas options\n# df_parsed = get_as_dataframe(worksheet, parse_dates=['birth_date'], skiprows=1, header=None)\n# print(df_parsed)","lang":"python","description":"This quickstart demonstrates how to read data from a Google Sheet into a pandas DataFrame using `get_as_dataframe` and write a DataFrame back to a sheet using `set_with_dataframe`. It includes a mock gspread worksheet for immediate runnability. In a real scenario, you'd authenticate with `gspread` (e.g., via a service account JSON file) and obtain a `worksheet` object from your Google Spreadsheet."},"warnings":[{"fix":"If you need to retain all rows and columns, including trailing empty ones, explicitly set `drop_empty_rows=False` and `drop_empty_columns=False` when calling `get_as_dataframe`.","message":"In version 4.0.0, the `get_as_dataframe` function's `drop_empty_rows` and `drop_empty_columns` parameters changed their default value to `True`. This means empty rows and columns at the end of a sheet will now be automatically discarded when reading, which might alter the DataFrame structure for existing code expecting these rows/columns.","severity":"breaking","affected_versions":"4.0.0 and later"},{"fix":"Upgrade to Python 3 or pin your `gspread-dataframe` dependency to a version compatible with Python 2.7 (e.g., `gspread-dataframe<4.0.0`).","message":"Version 4.0.0 and later of `gspread-dataframe` officially support Python 3 only. If you are using Python 2.7, you must use `gspread-dataframe` releases prior to 4.0.0 (e.g., 2.1.1 or earlier).","severity":"gotcha","affected_versions":"4.0.0 and later"},{"fix":"Ensure your `gspread` and `pandas` installations meet the minimum requirements for your `gspread-dataframe` version to avoid compatibility issues.","message":"`gspread-dataframe` requires specific versions of its core dependencies. For `gspread-dataframe` versions 4.0.0+, you need `gspread>=3.0.0` and `pandas>=0.24.0`. Using older `gspread-dataframe` versions (2.1.1 or earlier) is necessary if you are tied to older `gspread` versions.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Consult the pandas documentation for `pandas.read_csv` and ensure any passed options are compatible with the 'python' parsing engine. Process the DataFrame further with pandas after initial loading if more complex parsing is needed.","message":"The `get_as_dataframe` function uses the 'python' engine for pandas' text parsing, which means only options supported by this engine can be passed via the `**options` argument (e.g., `parse_dates`, `skiprows`, `header`). Some advanced `pandas.read_csv` options might not work.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Follow the `gspread` authentication guide to set up credentials correctly. Crucially, share your Google Sheet with the client email address specified in your service account JSON file or OAuth client ID.","message":"The underlying `gspread` library, and by extension `gspread-dataframe`, requires careful handling of Google Sheets API authentication (e.g., Service Account or OAuth Client ID) and explicit sharing of the target spreadsheet with the authenticated client email. Misconfiguration is a common source of `gspread.exceptions.SpreadsheetNotFound` or permission errors.","severity":"gotcha","affected_versions":"All versions (inherent to gspread)"},{"fix":"After loading the DataFrame, use `df['column'].astype(type)` or `pd.to_numeric(df['column'])`, `pd.to_datetime(df['column'])` to cast columns to their appropriate data types.","message":"When reading data from Google Sheets, `get_as_dataframe` may initially return all columns with a pandas 'object' dtype. This requires manual type conversion (e.g., to `int`, `float`, `datetime`) if numeric or date-time operations are intended.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}