GSpread Asyncio

2.0.0 verified Fri May 01 auth: no python

An asyncio wrapper for the gspread library for Google Sheets API. Version 2.0.0 brings compatibility with gspread 6.0 and includes breaking changes. Actively maintained, with releases every few months.

pip install gspread-asyncio

Common errors

error TypeError: AsyncioGspreadWorksheet.update() takes 2 positional arguments but 3 were given ↓

cause In v2.0.0, update() changed from (range_name, values) to (values, range_name).

fix

Call ws.update(values, range_name) or use keyword arguments: ws.update(values=[...], range_name='...')

error AttributeError: module 'gspread_asyncio' has no attribute 'AsyncioGspreadClient' ↓

cause Importing incorrectly, e.g., `from gspread_asyncio import AsyncioGspreadClient` but the class is named AsyncioGspreadClient or similar variant.

fix

Check the actual class name: from gspread_asyncio import AsyncioGspreadClientManager and then use .authorize() to get a client.

error RuntimeError: Task <Task pending ...> got Future <Future pending ...> attached to a different loop ↓

cause Mixing asyncio event loops, often due to creating the event loop after calling asyncio.run() or using multiple threads.

fix

Ensure all async code runs on the same event loop; prefer asyncio.run() over manual loop handling.

Warnings

breaking AsyncioGspreadWorksheet.update() argument order changed in v2.0.0: update(values, range_name) instead of update(range_name, values). ↓

fix Swap arguments or use keyword arguments: ws.update(values=[['a','b']], range_name='A1:B2')

deprecated AsyncioGspreadSpreadsheet.duplicate() is deprecated and will be removed in a future version; avoid using it. ↓

fix Use gspread's copy method or manual sheet duplication via API if necessary.

gotcha All gspread-asyncio methods must be awaited; forgetting await leads to coroutine objects instead of results. ↓

fix Ensure every call to a method returning a coroutine is preceded with await.

Imports

AsyncioGspreadClientManager

wrong

from gspread import AsyncioGspreadClientManager

correct

from gspread_asyncio import AsyncioGspreadClientManager

gspread itself does not have async classes

AsyncioGspreadClient
```
from gspread_asyncio import AsyncioGspreadClient
```
Not directly needed typically, use manager to get client

AsyncioGspreadSpreadsheet

from gspread_asyncio import AsyncioGspreadSpreadsheet

AsyncioGspreadWorksheet

from gspread_asyncio import AsyncioGspreadWorksheet

Quickstart

Authorize and read a cell value from a Google Sheet asynchronously.

import asyncio
from gspread_asyncio import AsyncioGspreadClientManager

def get_creds():
    # Replace with your own credentials
    return None

async def main():
    agcm = AsyncioGspreadClientManager(get_creds)
    agc = await agcm.authorize()
    ss = await agc.open_by_key('your_spreadsheet_key')
    ws = await ss.get_worksheet(0)
    val = await ws.acell('A1')
    print(val.value)

asyncio.run(main())