pola-rs/polars · error · ModuleUpgradeRequiredError

`autofit=True` requires xlsxwriter 3.0.8 or higher, found {x

Error message

`autofit=True` requires xlsxwriter 3.0.8 or higher, found {xlv}

What it means

Raised as ModuleUpgradeRequiredError by DataFrame.write_excel(autofit=True) when the installed xlsxwriter is older than 3.0.8. Worksheet-level `ws.autofit()` (sizing columns from content) was added to xlsxwriter in 3.0.8; older versions only support per-column set_column widths, so polars gates the convenience flag on that version and names the found version in the error.

Source

Thrown at py-polars/src/polars/dataframe/frame.py:3857

        # additional column-level properties
        if hidden_columns is None:
            hidden = set()
        elif isinstance(hidden_columns, str):
            hidden = {hidden_columns}
        else:
            hidden = set(_expand_selectors(df_original, hidden_columns))

        # Autofit section needs to be present above column_widths section
        # to ensure that parameters provided in the column_widths section
        # are not overwritten by autofit
        #
        # table/rows all written; apply (optional) autofit
        if autofit and not is_empty:
            xlv = xlsxwriter.__version__
            if parse_version(xlv) < (3, 0, 8):
                msg = f"`autofit=True` requires xlsxwriter 3.0.8 or higher, found {xlv}"
                raise ModuleUpgradeRequiredError(msg)
            ws.autofit()

        if isinstance(column_widths, int):
            column_widths = dict.fromkeys(df.columns, column_widths)
        else:
            column_widths = _expand_selector_dicts(  # type: ignore[assignment]
                df_original, column_widths, expand_keys=True, expand_values=False
            )
        column_widths = _unpack_multi_column_dict(column_widths or {})  # type: ignore[assignment]

        for column in df.columns:
            options = {"hidden": True} if column in hidden else {}
            col_idx = table_start[1] + df.get_column_index(column)
            if column in column_widths:  # type: ignore[operator]
                ws.set_column_pixels(
                    col_idx,
                    col_idx,
                    column_widths[column],  # type: ignore[index]

View on GitHub (pinned to df599052da)

Solutions

Upgrade xlsxwriter: `pip install -U 'xlsxwriter>=3.0.8'`
If you must keep the old version, drop autofit and set widths manually via `column_widths={...}`
Pin `'xlsxwriter>=3.0.8'` in project requirements to prevent regression

Example fix

# before (xlsxwriter 3.0.6)
df.write_excel('out.xlsx', autofit=True)  # ModuleUpgradeRequiredError

# after
# pip install -U 'xlsxwriter>=3.0.8'
df.write_excel('out.xlsx', autofit=True)
# or, without upgrading:
df.write_excel('out.xlsx', column_widths={c: 12 for c in df.columns})

Defensive patterns

Strategy: validation

Validate before calling

import xlsxwriter
if autofit and parse_version(xlsxwriter.__version__) < (3, 0, 8):
    df.write_excel('out.xlsx', column_widths={c: 12 for c in df.columns})
else:
    df.write_excel('out.xlsx', autofit=True)

Try / catch

try:
    df.write_excel('out.xlsx', autofit=True)
except ModuleUpgradeRequiredError as e:
    if 'xlsxwriter 3.0.8' in str(e):
        df.write_excel('out.xlsx', column_widths=12)
    else:
        raise

Prevention

Pin 'xlsxwriter>=3.0.8' whenever autofit output is required
Check xlsxwriter's version in your environment health check
Keep explicit column_widths as a portable fallback for locked-down environments

When it happens

Trigger: `df.write_excel('out.xlsx', autofit=True)` with xlsxwriter < 3.0.8 installed. The check runs after the table/rows are written but before autofit is applied, using `parse_version(xlsxwriter.__version__) < (3, 0, 8)`.

Common situations: Environments where an old xlsxwriter was pinned by another reporting library; fresh installs pulling a stale xlsxwriter from a lockfile; CI base images with preinstalled old versions; after downgrading xlsxwriter to dodge an unrelated bug.

Related errors

AI-assisted analysis of pola-rs/polars@df599052da (2026-08-16). Data as JSON: /api/errors/43d73e5f04e1cba8. Report an issue: GitHub.