gspread-formatting provides complete Google Sheets formatting support for gspread worksheets, allowing programmatic control over cell styles, conditional formatting, data validation, and more. The current version is 1.2.1. Releases occur periodically to add new features, fix bugs, and maintain compatibility with the underlying gspread library and Google Sheets API.
pip install gspread-formattingVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to initialize a gspread client (required for gspread-formatting), create or open a spreadsheet, define a custom `CellFormat` object, and apply it to a specific cell range using `format_cell_range`.
Upgrade gspread-formatting to version 1.0.0 or higher: `pip install --upgrade gspread-formatting`.
Be mindful that formatting operations are generally 'set' operations. If you need to incrementally update formats, retrieve the current format first, modify it, then reapply. E.g., `get_user_entered_format(worksheet, 'A1')`.
Refer to the official Google Sheets API documentation for `CellFormat`, `TextFormat`, `Color`, etc., to understand all available properties and their valid values. Experiment with small examples to verify complex formats before applying them broadly.
Ensure your `gspread` client is correctly authenticated and has the necessary permissions for the target spreadsheet. Handle `gspread.exceptions` appropriately for network or permission-related errors. Be aware of Google Sheets API rate limits for extensive formatting operations.
Run `pip install gspread-formatting` in your terminal to install the package.
Ensure the 'values' parameter for `BooleanCondition` is always a list or tuple, even if it contains only one element. For example, use `values=[100]` instead of `values=100`.
Consolidate multiple formatting operations into single API calls using batch functions provided by `gspread-formatting`, such as `format_cell_ranges()`, `set_column_widths()`, `set_row_heights()`, and using `ConditionalFormatRule.save()` after modifying rules.
Import the required formatting functions from `gspread_formatting` (e.g., `from gspread_formatting import format_cell_range`) and then call them, passing your `worksheet` object as an argument, like `format_cell_range(worksheet, 'A1:B1', fmt)`.