Formatting basics

The handful of options that make a sheet readable

A default export is a bare grid: unstyled header, columns sized to nothing in particular, nothing frozen. These options fix that, and they’re the ones worth knowing by heart.

Headers

styled_headers · bool · default: "False"

Bolds the first row. Verified against 0.3.1: this applies bold only, with no fill, despite the source describing it as bold plus gray.

write_header_row · bool · default: "True"

Whether column names are written at all. Set False when appending to a template that already has headers, or exporting data only.

If you want shaded headers, add a cell_styles entry with a fill for each header cell. styled_headers won’t do it.

Freezing and filtering

freeze_rows · int · default: "0"

Rows that stay in place while the rest scrolls. 1 pins the header.

freeze_cols · int · default: "0"

Same for columns. 1 pins the leftmost column, which helps when it holds names or IDs.

auto_filter · bool · default: "False"

Adds filter dropdowns to the header row.

jet.write_sheet_arrow(
    df.to_arrow(), "out.xlsx",
    styled_headers=True,
    freeze_rows=1,
    freeze_cols=1,
    auto_filter=True,
)

Column widths

auto_width · bool · default: "False"

Sizes every column to fit its contents.

column_widths · dict[str, float | str]

Per-column override keyed by column name. Accepts a number in Excel character units, a pixel string such as "150px", or "auto".

The two combine. Turn on auto_width and override only the columns that need it:

jet.write_sheet_arrow(
    df.to_arrow(), "out.xlsx",
    auto_width=True,
    column_widths={
        "ID": 8.0,           # narrow, fixed
        "Notes": 60.0,       # wide for prose
        "Email": "200px",    # pixels if you prefer
    },
)

auto_width reads every row to measure content, so it costs time on large frames. On a million-row export, set explicit widths instead. The project’s own guidance is to disable auto-width for speed.

Row heights

row_heights · dict[int, float]

Height in points, keyed by 1-based row number.

default_row_height · float

Applies to every row. Excel’s own default is 15.

Header content above the data

When a report needs a title block above the table, write it with header_content and push the DataFrame down with data_start_row.

header_content · list[tuple[int, int, str]]

Tuples of (row, col, text) written before the data. Rows are 1-based, columns 0-based.

data_start_row · int · default: "0"

Row where the DataFrame begins. It also excludes the rows above it from auto_width measurement, so a long title doesn’t stretch column A.

jet.write_sheet_arrow(
    df.to_arrow(), "report.xlsx",
    header_content=[
        (1, 0, "ACME Corporation"),
        (2, 0, "Q4 Sales Report"),
        (3, 0, "Generated 2026-01-15"),
    ],
    data_start_row=5,
    write_header_row=True,
    auto_width=True,
    merge_cells=[(1, 0, 1, 1)],
)

Row and column indexing isn’t consistent across the API. See Conventions for the full table before you set positions.

Putting it together

jet.write_sheet_arrow(
    df.to_arrow(),
    "employees.xlsx",
    sheet_name="Employees",
    styled_headers=True,
    freeze_rows=1,
    auto_filter=True,
    auto_width=True,
    column_formats={"Salary": "currency"},
)