{"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":"python","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,"search_vec":"'4.0.0':8 'act':26 'activ':50 'conveni':35 'convert':38 'data':40,70 'data-io':69 'datafram':3,6,24,42,67 'extens':29 'focus':54 'function':36 'googl':20,59,65 'gspread':2,5,32,63 'gspread-datafram':1,4 'integr':57 'io':71 'librari':12,33,48 'maintain':51 'panda':23,62,64 'provid':34 'python':11 'read':15 'seamless':56 'sheet':21,60,66 'simplifi':14 'spreadsheet':68 'use':22 'versa':46 'version':7 'vice':45 'vice-versa':44 'worksheet':39 'write':18","created_at":"2026-04-09T18:41:40.766376+00:00","updated_at":"2026-04-16T15:30:09.628174+00:00","problems":[{"fix":"Install the library using pip: `pip install gspread-dataframe`","cause":"The `gspread-dataframe` library is not installed in the Python environment you are using.","error":"ModuleNotFoundError: No module named 'gspread_dataframe'"},{"fix":"Ensure you have imported the function: `from gspread_dataframe import set_with_dataframe` (and `pip install gspread-dataframe` if not already installed).","cause":"The `set_with_dataframe` function was called without being properly imported from the `gspread_dataframe` module, or the library itself is not installed.","error":"NameError: name 'set_with_dataframe' is not defined"},{"fix":"To replace the sheet's content entirely and resize it to fit the DataFrame, use `set_with_dataframe(worksheet, dataframe, replace=True)`. For very large datasets, consider resizing the sheet to 1x1 first: `worksheet.resize(1, 1)`.","cause":"Attempting to write a pandas DataFrame to a Google Sheet that would exceed Google Sheets' maximum cell limit (10 million cells) due to the DataFrame's size or the sheet's current dimensions.","error":"This action would increase the number of cells in the workbook above the limit of 10000000 cells."},{"fix":"Convert problematic DataFrame columns to standard Python types or strings before writing. For example, `df = df.astype(object)` or convert specific columns: `df['int_column'] = df['int_column'].astype(int)` or `df['float_column'] = df['float_column'].astype(float)`.","cause":"When writing a pandas DataFrame to Google Sheets, some NumPy-specific data types (like `numpy.int64` or `numpy.float64`) are not directly JSON serializable by the Google Sheets API.","error":"TypeError: Object of type int64 is not JSON serializable"},{"fix":"Upgrade your `gspread` library to the latest version: `pip install --upgrade gspread`. Ensure `gspread-dataframe` is also updated to a compatible version.","cause":"This error occurs when an older version of the `gspread` library is installed. The `service_account` method for authentication was introduced in `gspread` v4.0.0.","error":"AttributeError: module 'gspread' has no attribute 'service_account'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"4.0.0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/robin900/gspread-dataframe","docs":null,"changelog":null,"pypi":"https://pypi.org/project/gspread-dataframe/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["gcp","data"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-28","next_check":"2026-07-28","install_tag":null}}