# burnash/gspread: the mature Python client for Google Sheets, now asking for a maintainer

> Seven thousand five hundred stars, three tagged 6.x releases, a real migration guide from v5, and a README banner at the top saying the maintainers cannot keep it going and are looking for help.

**burnash/gspread** — Google Sheets Python API

- Repository: https://github.com/burnash/gspread
- Website: https://docs.gspread.org
- Stars: 7,513 · Forks: 981
- Language: Python
- License: MIT
- Published: 2026-10-06 · Updated: 2026-10-06 · Language: en
- Canonical page: https://hysenlabs.com/projects/burnash-gspread

## The README opens with a maintainer notice

Before anything else, the README says this. There is a section titled Maintainer needed, and it states that the maintainers are sorry to announce they are currently unable to maintain Gspread, that they are looking for new maintainers to keep up the good work, and that people should reach out through issue 1570.

That framing matters for how you read everything else on the page. The repository is not archived, the last push recorded is 2026-07-30, and the metadata lists three maintainers, Alexandre Lavigne, alifeee, and the original author Anton Burnashev in the authors field. So this is not a dead project with a banner bolted on. It is a project that shipped through 2025 and is now openly asking for someone to own it.

The stars tell you how much rides on the answer. 7,507 stars and 978 forks, with 73 open issues. A fork count that high relative to stars is what you see when people vendor gspread into an internal package and pin it.

The honest way to frame any decision here is that the library itself is in good shape and the governance is the open question. Nothing in the code layout suggests decay, but a client library for an external API is a maintenance liability by nature, because Google can change its Sheets API v4 underneath you and somebody has to notice.

## Four features and one install line

The Overview section is unusually short, and that is a compliment to the design. Four bullets cover the whole capability list: open a spreadsheet by title, key or URL; read, write and format cell ranges; sharing and access control; batching updates.

Installation is a single line, and the requirement is stated next to it.

```bash
pip install gspread
```

Requirements: Python 3.8+. That floor matches `pyproject.toml`, which sets `requires-python = ">=3.8"` and lists classifiers for 3.8, 3.9, 3.10 and 3.11.

Four bullets is enough because the API is one object wide. You get a client from a factory, you open a spreadsheet, and everything hangs off a worksheet object. There is no session abstraction, no query builder and no ORM layer to learn before you write a value to a cell. For a script that needs to read a config spreadsheet or dump a dataframe into a shared sheet, that narrowness is the feature.

What the four bullets do not mention is batching, which is listed, or how authentication works, which is the first numbered step of Basic Usage and links out to the Google API Console instructions. The line between what this library does and what you configure in Google's own console is where most of the real setup time goes.

## Authentication is three factories and a console visit

Step one of the basic usage is to create credentials in the Google API Console, and step two is the code. The comment inside the code block names the three routes without choosing one for you.

```python
import gspread

# First you need access to the Google API. Based on the route you
# chose in Step 1, call either service_account(), oauth() or api_key().
gc = gspread.service_account()

# Open a sheet from a spreadsheet in one go
wks = gc.open("Where is the money Lebowski?").sheet1

# Update a range of cells using the top left corner address
wks.update([[1, 2], [3, 4]], "A1")

# Or update a single cell
wks.update_acell("B42", "it's down there somewhere, let me take another look.")

# Format the header
wks.format('A1:B1', {'textFormat': {'bold': True}})
```

Three factories, `service_account()`, `oauth()` and `api_key()`, cover the three ways you can hold Google credentials, and the library does not pretend one of them is the default. A service account is the right answer for automation because it authenticates as a machine identity you own rather than as a person, at the cost of having to share each spreadsheet with the service account's address.

The rest of the block is worth reading as an API tour in six lines. `.open()` takes a title and chains straight to `.sheet1`, so the shortest useful program is one line long. `update()` takes a two dimensional array and a range label. `update_acell()` is the single cell convenience. `format()` takes a range and a nested dict describing the format, here a bold text format applied across a header row.

The formatting dict is the one design decision that will surprise you if you came from another Sheets client. It is a nested structure keyed by Sheets API field names such as `textFormat`, passed through rather than wrapped, which keeps the library thin at the cost of making you learn Google's own vocabulary.

## The v5 to v6 migration is the most useful page in the repo

Most libraries of this age have a changelog. gspread has a migration guide, and it is more valuable than a changelog because it tells you exactly which existing code stops working.

The headline change is argument order on `Worksheet.update`. The first two arguments, `values` and `range_name`, have swapped, and `values` can no longer be a flat list. The guide gives both a positional form and the named-argument form that works across v5 and v6, which is the practical detail: if you are not ready to fix every call site, name your arguments.

Then there is a run of smaller breaks. Colours move from a dictionary to hexadecimal strings, with `gspread.utils.convert_colors_to_hex_value()` offered as a bridge. `lastUpdateTime` stops being a property and becomes the method `get_lastUpdateTime()`. `Worksheet.get_records()` is removed outright, and the replacement path is spelled out: fetch the header row, fetch the cell range you want, and combine them with `gspread.utils.to_records()`.

Two more details are practical rather than API. Deprecation warnings from v5 can be silenced by setting the `GSPREAD_SILENCE_WARNINGS` environment variable to `1`. And `Worksheet.__init__` gained more data, so code that constructed a worksheet directly now needs to pass the spreadsheet id and the http client as well as the properties.

The pattern across all of these is worth naming: nothing was removed without a documented path forward. That is what a library at 7,500 stars has to do, and the guide is long enough to show somebody took the trouble.

## Three reading styles for the same grid

The More Examples section is where the README gets long, and it is organized by task rather than by class, which makes it easy to skim for the one thing you need.

Opening has three forms, matching the three ways a spreadsheet is identified: `gc.open('My poor gym results')` by title, `gc.open_by_key()` with the key pulled from a URL, and `gc.open_by_url()` when you have the whole URL to hand. The comments in that block are casual about it, one of them says look ma, no keys, which tells you the author considered the title form the happy path.

Worksheet selection follows the same pattern of three conveniences: `get_worksheet(0)` by index, `worksheet("January")` by title, and `sheet1` for the common case. Bulk operations are `worksheets()` to list and `add_worksheet(title=, rows=, cols=)` to create.

Reads are where the options multiply, and the three `get()` variants are the interesting part. A plain `get("A1:B4")` returns only cells that have values, so a sparse range comes back ragged. Passing `pad_values=True` returns a rectangular array padded with empty strings. Passing `maintain_size=True` returns an array matching the requested size exactly. Those three flags are the difference between a shape you have to normalise yourself and one you do not, and they are worth remembering.

For iteration there is `row_values(1)`, `col_values(1)`, and a `GridRangeType.ListOfLists` return type imported from `gspread.utils` when you want the whole sheet as a list of lists.

## Flit packaging and a mostly quiet release history

The build system moved to flit, which is visible in the packaging metadata and explains why version and description are marked dynamic rather than written by hand.

```toml
[build-system]
requires = ["flit_core >=3.2,<4"]
build-backend = "flit_core.buildapi"

[project]
name = "gspread"
requires-python = ">=3.8"
dynamic = ["version", "description"]

dependencies = ["google-auth>=1.12.0", "google-auth-oauthlib>=0.4.1"]
```

Two runtime dependencies, both from the google-auth family, and no requests pin or urllib3 in sight, which tells you the HTTP layer is inherited from the Google auth stack rather than rolled locally.

The metadata is otherwise careful. `Development Status :: 5 - Production/Stable` is still asserted, the license file is referenced rather than inlined, and `[tool.flit.sdist]` pulls `docs/` and `HISTORY.rst` into the source distribution so the long description and the changelog travel with the sdist. There is a `[tool.setuptools.package-data]` entry shipping `gspread/py.typed`, so the package ships type information, which matches the typed portion of the test suite mentioned in the release notes.

The release record is short and quiet. v6.2.1 published 2025-05-14, v6.2.0 on 2025-02-27, v6.1.4 on 2024-10-20 with nothing but a changelog link. What v6.2.1 actually contains is a good summary of how the project is maintained: a fixed auth snippet in the public docs, a clarified first step for authentication, a typo fix in community.rst, a rearranged flow that removes a reference to `creds`, a pip-audit safety switch, and an error message that now includes duplicate column names. Documentation accuracy and dependency security, no sweeping API changes.

The repository tree matches that picture: `gspread/` for the package, `tests/`, `docs/`, `tox.ini`, and separate `lint-requirements.txt` and `test-requirements.txt` so lint tooling stays out of the runtime environment.

## Conclusion

gspread is the answer to a question most people ask once, how do I talk to Google Sheets from Python, and it answers it with a small, well documented client whose API surface has stayed stable long enough that tutorials from years back still run. The migration guide from 5.12 to 6.0 is the clearest sign of that: argument orders, colour formats and deprecation warnings all get explicit treatment rather than a silent break. What sits at the top of the README today is harder to gloss over, a notice that the maintainers are unable to continue and are recruiting through issue 1570, with three named maintainers still listed in `pyproject.toml`. Start with the `service_account()` path in the README if you are wiring this into something automated, and read the `HISTORY.rst` entry for your version before upgrading, because the 6.0 boundary is where the code samples on the wider web stop matching.

## FAQ

### How do I install Gspread?

Run `pip install gspread`. The README states the requirement as Python 3.8 or newer, and the packaging metadata sets `requires-python = ">=3.8"` with classifiers through 3.11. Runtime dependencies are google-auth and google-auth-oauthlib, both pulled in automatically.

### How do I authenticate with Google Sheets in Python?

Create credentials in the Google API Console first, then call one of three factories on gspread: `service_account()`, `oauth()` or `api_key()`. The choice depends on which route you set up in the console, and the README deliberately does not pick one. `service_account()` is the usual choice for unattended automation.

### Is gspread still maintained or looking for new maintainers?

The README carries a Maintainer needed notice stating that the current maintainers are unable to maintain the project and are recruiting through issue 1570. The repository is not archived, the last recorded push is 2026-07-30, and `pyproject.toml` still lists three maintainers. The last tagged release, v6.2.1, published on 2025-05-14.

## Sources

- [burnash/gspread on GitHub](https://github.com/burnash/gspread)
- [License: MIT](https://github.com/burnash/gspread/blob/master/LICENSE)
- [Project website](https://docs.gspread.org)
- [README](https://github.com/burnash/gspread/blob/master/README.md)
- [Releases](https://github.com/burnash/gspread/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/burnash-gspread