---
id: gspread-formatting
version: "1.2.1"
license: MIT
license_treatment: permissive
maintenance: aging
---

# gspread-formatting — Complete Google Sheets formatting support for gspread worksheets

License: permissive · Maintenance: aging · Downloads: 1.2M/mo

## What it is and what it does

gspread-formatting extends the gspread library with a complete API for styling Google Sheets. It wraps the v4 Sheets API's CellFormat specification, exposing all formatting components—background colors, text formatting, alignment, borders, and more—as Python classes that can be composed and applied to cell ranges. The package also handles worksheet-level operations like freezing rows and columns, setting row heights and column widths, managing data validation rules, and supporting right-to-left text direction.

The library is designed to work seamlessly with gspread's worksheet objects. You build format objects by instantiating classes with camelCase keyword arguments, then apply them to ranges using functions like format_cell_range or format_cell_ranges. For users working with Pandas DataFrames, a separate dataframe module provides convenience functions to format worksheets based on DataFrame structure. Format objects are composable, comparable, and support set-like operations (union, difference, intersection).

Use it for:

- Style header rows with background colors, bold text, and centered alignment in a report spreadsheet.
- Apply data validation rules to restrict cell inputs to predefined lists or numeric ranges.
- Format a worksheet populated from a Pandas DataFrame with custom header colors and number formatting.
- Freeze the first row and first column of a large data table for easier navigation.
- Set column widths and row heights to match content and improve readability of exported data.
- Apply conditional formatting rules to highlight cells based on values or conditions.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Adds complete cell formatting support to gspread, enabling you to style Google Sheets cells with colors, fonts, alignment, and conditional formatting, plus control frozen rows/columns and data validation.

Yes. The package is stable, actively maintained, has no security vulnerabilities, and solves a real gap in gspread's capabilities. If you need to programmatically format Google Sheets beyond basic data entry, this is the standard tool. The low install friction and permissive license make adoption straightforward.

## Install

pip install gspread-formatting
uv add gspread-formatting
poetry add gspread-formatting

## Installing gspread-formatting

Before you install: Low install friction with a single runtime dependency on gspread. The package is in production/stable status and actively maintained, with a recent release in March 2025 and no known vulnerabilities.

License in practice: MIT license is permissive; you can use this package freely in commercial and private projects with minimal restrictions.

Quickstart:

pip install gspread-formatting

from gspread_formatting import cellFormat, color, format_cell_range

fmt = cellFormat(
    backgroundColor=color(1, 0.9, 0.9),
    textFormat={'bold': True},
    horizontalAlignment='CENTER'
)
format_cell_range(worksheet, 'A1:J1', fmt)

Requires an authenticated gspread worksheet object; you must have gspread set up with Google Sheets API credentials.

Verify before relying:

- Whether the package supports all v4 Sheets API CellFormat features or only a subset of them.
- Performance characteristics when formatting large ranges or many cells in a single operation.
- Compatibility with recent versions of gspread and any breaking changes in the Sheets API.

## Package facts

- License: MIT (permissive)
- Python support: unspecified
- Install friction: low
- Maintenance: aging
- Downloads: 1.2M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

google sheets cell formatting, gspread formatting library, style google spreadsheet cells, conditional formatting google sheets, spreadsheet cell format api, frozen rows columns sheets, data validation google sheets, google-sheets, spreadsheet-formatting, data-export

[View on SkillFed](https://skillfed.io/packages/gspread-formatting) · [View on PyPI](https://pypi.org/project/gspread-formatting/)