googlesheets4 (development version) Unreleased

User interface

The user interface has gotten more stylish, thanks to the cli package (

The googlesheets4_quiet option can be used to suppress messages from googlesheets4, specifically (#163). By default, googlesheets4 always messages, i.e. it is not quiet. local_gs4_quiet() and with_gs4_quiet() are withr-style convenience helpers for setting googlesheets4_quiet = TRUE.

googlesheets4 now throws errors with class "googlesheets4_error" (#12).

Dependency changes

  • cli is new in Imports.

  • googlesheets4 Suggests testthat >= 3.0.0 and, specifically, uses third edition features.

googlesheets4 0.3.0 2021-03-04

All requests are now made with retry capability. Specifically, when a request fails due to a 429 RESOURCE_EXHAUSTED error, it is retried a few times, with suitable delays. Note that if it appears that you personally have exhausted your quota (more than 100 requests in 100 seconds), the initial waiting time is 100 seconds and this indicates you need to get your own OAuth app or service account.

When googlesheets4 and googledrive are used together in the same session, we alert you if you’re logged in to these package with different Google identities.

gs4_get() retrieves information about protected ranges.

googlesheets4 0.2.0 2020-05-08

googlesheets4 can now write and modify Sheets.

Several new articles are available at

Function naming scheme

The universal sheets_ prefix has been replaced by a scheme that conveys more information about the scope of the function. There are three prefixes:

  • gs4_: refers variously to the googlesheets4 package, v4 of the Google Sheets API, or to operations on one or more (spread)Sheets
  • sheet_: operations on one or more (work)sheets
  • range_: operations on a range of cells

The addition of write/edit functionality resulted in many new functions and the original naming scheme proved to be problematic. The article Function and class names contains more detail.

Any function present in the previous CRAN release, v0.1.1, still works, but triggers a warning with strong encouragement to switch to the current name.

Write Sheets

googlesheets4 now has very broad capabilities around Sheet creation and modification. These functions are ready for general use but are still marked experimental, as they may see some refinement based on user feedback.

(Work)sheet operations

The sheet_*() family of functions operate on the (work)sheets inside an existing (spread)Sheet:

Range operations

range_speedread() reads from a Sheet using its “export=csv” URL and, therefore, uses readr-style column type specification. It still supports fairly general range syntax and auth. For very large Sheets, this can be substantially faster than read_sheet().

range_read_cells() (formerly known as sheets_cells()) gains two new arguments that make it possible to get more data on more cells. By default, we get only the fields needed to parse cells that contain values. But range_read_cells(cell_data = "full", discard_empty = FALSE) is now available if you want full cell data, including formatting, even for cells that have no value (#4).

range_autofit() adjusts column width or row height to fit the data. This only affects the display of a sheet and does not change values or dimensions.

Printing a Sheet ID

The print method for sheets_id objects now attempts to reveal the current Sheet metadata available via gs4_get(), i.e. it makes an API call (but it should never error).

Other changes and additions

gs_formula() implements a vctrs S3 class for storing Sheets formulas.

gs4_fodder() is a convenience function that creates a filler data frame you can use to make toy sheets you’re using to practice on or for a reprex.

Renamed classes

The S3 class sheets_Spreadsheet is renamed to googlesheets4_spreadsheet, a consequence of rationalizing all internal and external classes (detailed in the article Function and class names). googlesheets4_spreadsheet is the class that holds metadata for a Sheet and it is connected to the API’s Spreadsheet schema. The return value of gs4_get() has this class.

Bug fixes

  • read_sheet() passes its na argument down to the helpers that parse cells, so that na actually has the documented effect (#73).

googlesheets4 0.1.1 2020-03-21

  • Patch release to modify a test fixture, to be compatible with tibble v3.0. Related to tibble’s increased type strictness.

googlesheets4 0.1.0 2019-11-04

  • Added a file to track changes to the package.