Package: gspread
Google Spreadsheets Python API v4Simple interface for working with Google Sheets.Features:Open a spreadsheet bytitle,keyorURL.Read, write, and format cell ranges.Sharing and access control.Batching updates.InstallationpipinstallgspreadRequirements: Python 3.8+.Basic UsageCreate credentials in Google API ConsoleStart using gspreadimportgspreadgc=gspread.service_account()# Open a sheet from a spreadsheet in one gowks=gc.open("Where is the money Lebowski?").sheet1# Update a range of cells using the top left corner addresswks.update('A1',[[1,2],[3,4]])# Or update a single cellwks.update('B42',"it's down there somewhere, let me take another look.")# Format the headerwks.format('A1:B1',{'textFormat':{'bold':True}})v5.12 to v6.0 Migration GuideUpgrade from Python 3.7Python 3.7 isend-of-life. gspread v6 requires a minimum of Python 3.8.ChangeWorksheet.updateargumentsThe first two arguments (values&range_name) have swapped (torange_name&values). Either swap them (works in v6 only), or use named arguments (works in v5 & v6).As well,valuescan no longer be a list, and must be a 2D array.- file.sheet1.update([["new", "values"]])+ file.sheet1.update([["new", "values"]]) # unchanged- file.sheet1.update("B2:C2", [["54", "55"]])+ file.sheet1.update([["54", "55"]], "B2:C2")# or+ file.sheet1.update(range_name="B2:C2", values=[["54", "55"]])MoreSee More Migration GuideChange colors from dictionary to textv6 uses hexadecimal color representation. Change all colors to hex. You can use the compatibility functiongspread.utils.convert_colors_to_hex_value()to convert a dictionary to a hex string.- tab_color = {"red": 1, "green": 0.5, "blue": 1}+ tab_color = "#FF7FFF"file.sheet1.update_tab_color(tab_color)Switch lastUpdateTime from property to method- age = spreadsheet.lastUpdateTime+ age = spreadsheet.get_lastUpdateTime()Replace methodWorksheet.get_recordsIn v6 you can now only getallsheet records, usingWorksheet.get_all_records(). The methodWorksheet.get_records()has been removed. You can get some records using your own fetches and combine them withgspread.utils.to_records().+ from gspread import utilsall_records = spreadsheet.get_all_records(head=1)- some_records = spreadsheet.get_all_records(head=1, first_index=6, last_index=9)- some_records = spreadsheet.get_records(head=1, first_index=6, last_index=9)+ header = spreadsheet.get("1:1")[0]+ cells = spreadsheet.get("6:9")+ some_records = utils.to_records(header, cells)Silence warningsIn version 5 there are many warnings to mark deprecated feature/functions/methods.
They can be silenced by setting theGSPREAD_SILENCE_WARNINGSenvironment variable to1Add more data togspread.Worksheet.__init__gc = gspread.service_account(filename="google_credentials.json")spreadsheet = gc.open_by_key("{{key}}")properties = spreadsheet.fetch_sheet_metadata()["sheets"][0]["properties"]- worksheet = gspread.Worksheet(spreadsheet, properties)+ worksheet = gspread.Worksheet(spreadsheet, properties, spreadsheet.id, gc.http_client)More ExamplesOpening a Spreadsheet# You can open a spreadsheet by its title as it appears in Google Docssh=gc.open('My poor gym results')# <-- Look ma, no keys!# If you want to be specific, use a key (which can be extracted from# the spreadsheet's url)sht1=gc.open_by_key('0BmgG6nO_6dprdS1MN3d3MkdPa142WFRrdnRRUWl1UFE')# Or, if you feel really lazy to extract that key, paste the entire urlsht2=gc.open_by_url('https://docs.google.com/spreadsheet/ccc?key=0Bm...FE&hl')Creating a Spreadsheetsh=gc.create('A new spreadsheet')# But that new spreadsheet will be visible only to your script's account.# To be able to access newly created spreadsheet you *must* share it# with your email. Which brings us to…Sharing a Spreadsheetsh.share('otto@example.com',perm_type='user',role='writer')Selecting a Worksheet# Select worksheet by index. Worksheet indexes start from zeroworksheet=sh.get_worksheet(0)# By titleworksheet=sh.worksheet("January")# Most common case: Sheet1worksheet=sh.sheet1# Get a list of all worksheetsworksheet_list=sh.worksheets()Creating a Worksheetworksheet=sh.add_worksheet(title="A worksheet",rows="100",cols="20")Deleting a Worksheetsh.del_worksheet(worksheet)Getting a Cell Value# With labelval=worksheet.get('B1').first()# With coordsval=worksheet.cell(1,2).valueGetting All Values From a Row or a Column# Get all values from the first rowvalues_list=worksheet.row_values(1)# Get all values from the first columnvalues_list=worksheet.col_values(1)Getting All Values From a Worksheet as a List of Listsfromgspread.utilsimportGridRangeTypelist_of_lists=worksheet.get(return_type=GridRangeType.ListOfLists)Getting a range of valuesReceive only the cells with a value in them.>>>worksheet.get("A1:B4")[['A1','B1'],['A2']]Receive a rectangular array around the cells with values in them.>>>worksheet.get("A1:B4",pad_values=True)[['A1','B1'],['A2','']]Receive an array matching the request size regardless of if values are empty or not.>>>worksheet.get("A1:B4",maintain_size=True)[['A1','B1'],['A2',''],['',''],['','']]Finding a Cell# Find a cell with exact string valuecell=worksheet.find("Dough")print("Found something at R%sC%s"%(cell.row,cell.col))# Find a cell matching a regular expressionamount_re=re.compile(r'(Big|Enormous) dough')cell=worksheet.find(amount_re)Finding All Matched Cells# Find all cells with string valuecell_list=worksheet.findall("Rug store")# Find all cells with regexpcriteria_re=re.compile(r'(Small|Room-tiering) rug')cell_list=worksheet.findall(criteria_re)Updating Cells# Update a single cellworksheet.update('B1','Bingo!')# Update a rangeworksheet.update('A1:B2',[[1,2],[3,4]])# Update multiple ranges at onceworksheet.batch_update([{'range':'A1:B2','values':[['A1','B1'],['A2','B2']],},{'range':'J42:K43','values':[[1,2],[3,4]],}])DocumentationDocumentation:https://gspread.readthedocs.io/Ask QuestionsThe best way to get an answer to a question is to ask onStack Overflow with a gspread tag.ContributorsList of contributorsHow to ContributePlease make sure to take a moment and read theCode of Conduct.Report IssuesPlease report bugs and suggest features via theGitHub Issues.Before opening an issue, search the tracker for possible duplicates. If you find a duplicate, please add a comment saying that you encountered the problem as well.Improve DocumentationDocumentationis as important as code. If you know how to make it more consistent, readable and clear, please submit a pull request. The documentation files are indocsfolder, usereStructuredTextmarkup and rendered bySphinx.Contribute codePlease make sure to read theContributing Guidebefore making a pull request.