{"record":{"id":"43d73e5f04e1cba8","repo":"pola-rs/polars","slug":"autofit-true-requires-xlsxwriter-3-0-8-or-higher","errorCode":null,"errorMessage":"`autofit=True` requires xlsxwriter 3.0.8 or higher, found {xlv}","messagePattern":"`autofit=True` requires xlsxwriter 3\\.0\\.8 or higher, found (.+?)","errorType":"exception","errorClass":"ModuleUpgradeRequiredError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/dataframe/frame.py","lineNumber":3857,"sourceCode":"\n        # additional column-level properties\n        if hidden_columns is None:\n            hidden = set()\n        elif isinstance(hidden_columns, str):\n            hidden = {hidden_columns}\n        else:\n            hidden = set(_expand_selectors(df_original, hidden_columns))\n\n        # Autofit section needs to be present above column_widths section\n        # to ensure that parameters provided in the column_widths section\n        # are not overwritten by autofit\n        #\n        # table/rows all written; apply (optional) autofit\n        if autofit and not is_empty:\n            xlv = xlsxwriter.__version__\n            if parse_version(xlv) < (3, 0, 8):\n                msg = f\"`autofit=True` requires xlsxwriter 3.0.8 or higher, found {xlv}\"\n                raise ModuleUpgradeRequiredError(msg)\n            ws.autofit()\n\n        if isinstance(column_widths, int):\n            column_widths = dict.fromkeys(df.columns, column_widths)\n        else:\n            column_widths = _expand_selector_dicts(  # type: ignore[assignment]\n                df_original, column_widths, expand_keys=True, expand_values=False\n            )\n        column_widths = _unpack_multi_column_dict(column_widths or {})  # type: ignore[assignment]\n\n        for column in df.columns:\n            options = {\"hidden\": True} if column in hidden else {}\n            col_idx = table_start[1] + df.get_column_index(column)\n            if column in column_widths:  # type: ignore[operator]\n                ws.set_column_pixels(\n                    col_idx,\n                    col_idx,\n                    column_widths[column],  # type: ignore[index]","sourceCodeStart":3839,"sourceCodeEnd":3875,"githubUrl":"https://github.com/pola-rs/polars/blob/df599052daf96e7a9cc30a3b0c6bd25d6947e3c0/py-polars/src/polars/dataframe/frame.py#L3839-L3875","documentation":"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.","triggerScenarios":"`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)`.","commonSituations":"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.","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"],"exampleFix":"# before (xlsxwriter 3.0.6)\ndf.write_excel('out.xlsx', autofit=True)  # ModuleUpgradeRequiredError\n\n# after\n# pip install -U 'xlsxwriter>=3.0.8'\ndf.write_excel('out.xlsx', autofit=True)\n# or, without upgrading:\ndf.write_excel('out.xlsx', column_widths={c: 12 for c in df.columns})","handlingStrategy":"validation","validationCode":"import xlsxwriter\nif autofit and parse_version(xlsxwriter.__version__) < (3, 0, 8):\n    df.write_excel('out.xlsx', column_widths={c: 12 for c in df.columns})\nelse:\n    df.write_excel('out.xlsx', autofit=True)","typeGuard":null,"tryCatchPattern":"try:\n    df.write_excel('out.xlsx', autofit=True)\nexcept ModuleUpgradeRequiredError as e:\n    if 'xlsxwriter 3.0.8' in str(e):\n        df.write_excel('out.xlsx', column_widths=12)\n    else:\n        raise","preventionTips":["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"],"tags":["excel","version-mismatch","dependency","xlsxwriter"],"backgroundTag":null,"analyzedSha":"df599052daf96e7a9cc30a3b0c6bd25d6947e3c0","analyzedAt":"2026-08-16T12:10:03.978Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}