NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
PyPI, #206 most downloaded on PyPI
A Python module for creating Excel XLSX files.
Latest stable
3.3.4
Last release today
22 Nov 2026
Ships unpredictably
gaps range from 8 days to 1.1 years
Nearly every release is documented
notes for 60 of the last 60 stable releases
1 version withdrawn
withdrawn after publishing
14 years old
180 releases · first in 2013
Drag across the ruler to compare, or tap a release to open it.
Added support for custom ribbon UI XML files via the add_custom_ui method. See customui.
Added support for custom ribbon UI XML files via the add_custom_ui method. See customui.
Fixed issue where datetimes on 1900-02-28 with a time after midnight were written as 1900-02-29.
Added support for worksheet pivot tables via the add_pivot_table method. Pivot tables can have row, column, filter and value fields, and the value fie
Added support for worksheet pivot tables via the add_pivot_table method. Pivot tables can have row, column, filter and value fields, and the value fields can have different functions, custom names and number formats. The pivot table style, layout and grand totals can also be set. See pivot_tables and ex_pivot_table.
Note, the pivot table data isn't stored in the file. Excel builds the pivot table from the source data when the file is opened. As a result, applications that don't refresh pivot tables on load will show an empty pivot table, and Excel will ask to save the file on close even if no changes were made. See pivot_table_limitations for details.
Your coding agent can read these notes before it upgrades. Set up the MCP server →
Added documentation and examples for the excel_2023_theme, default_format_properties, default_row_height and default_column_width Workbook options. Se
Added documentation and examples for the excel_2023_theme, default_format_properties, default_row_height and default_column_width Workbook options. See ex_theme_excel_2023 and ex_theme_custom.
Fixed issue where a created date in set_properties was replaced with the current time if it was a datetime.date. Also allow a datetime.date in set_custom_property.
Fixed issue where timezone aware datetimes in set_properties and set_custom_property weren't converted to UTC.
Fixed issue where a rejected add_table, merge_range or autofilter could leave reserved cells that caused a later OverlappingRange exception.
Improved the performance of write_formula and other methods that handle formulas.
Fixed issue where function names in formula string literals, and names such as MYSINGLE(), were treated as "future" functions.
Fixed performance issue where positioning objects such as images and comments on a worksheet with a custom default row height.
Fixed performance issue where positioning objects such as images and comments on a worksheet with a custom default row height.
Fixed a (different) performance issue where positioning a large number of objects such as comments on a worksheet with custom row heights or column widths.
Fixed off by one error in the worksheet set_first_sheet() method.
Fixed issue where autofit() hid a column that had a user defined width narrower than the autofit width.
Fixed issue where add_table() didn't detect a duplicate header name when a user defined header matched a default ColumnN header.
Fixed issue where the strings_to_formulas Workbook option didn't prevent write() from converting strings like {=SUM(A1:B1*A2:B2)} to array formulas.
Fixed set_column() rounding a half-pixel width to the nearest even pixel, which made some widths one pixel narrower than in 3.2.9.
Fixed unescaped double quotes, and incorrect string lengths for characters such as emojis, in text type conditional formats.
Fixed issue where "future" functions such as ISFORMULA() weren't prefixed with _xlfn. in conditional_format() and data_validation() formulas. See formula_future.
Fixed Excel string length limit checks for strings with characters such as emojis, which Excel counts as 2 characters.
Added the set_zoom_to_fit() method for chartsheets. It ensures that a chartsheet is zoomed automatically by Excel to fit the screen even when the wind
Added the set_zoom_to_fit() method for chartsheets. It ensures that a chartsheet is zoomed automatically by Excel to fit the screen even when the window is resized.
Added alt text description and title options to worksheet Tables.
Added the use_custom_theme() method to change the default workbook theme to a user supplied .thmx, .xlsx or theme1.xml file, along with the default_format_properties, default_row_height and default_column_width constructor options to change the default font and cell size to match the theme.
Changed the exception raised for an unsupported source type in Image() and an unsupported theme type in use_custom_theme() from ValueError to TypeError.
Fixed issue where conditional format rule priorities were out of order when a cell range was repeated after a different range. The priorities now follow the order in which the rules were added.
Fixed issue where autofilter() didn't check that the range was within the worksheet limits, which could produce a corrupt file for large worksheets.
Fixed spurious "Invalid cell reference" warning when a chart series used a defined name with a sheet reference.
Fixed the width and height detection for large GIF images and for top-down BMP images, and added extra image dimension validation.
1188 and 1189.
Migrated the packaging configuration from setup.py to pyproject.toml with the license declared as a PEP 639 SPDX expression.
Removed the py.typed file since it was causing a lot of downstream CI failures where consumers weren't handling the xlsxwriter types correctly or taki
Removed the py.typed file since it was causing a lot of downstream CI
failures where consumers weren't handling the xlsxwriter types correctly or
taking them into account.
The file will be re-added once the xlsxwriter typing is more comprehensive.
Fixed mypy implicit export error caused by the Workbook() type annotations changes in v3.2.7 and v3.2.6.
Fixed mypy implicit export error caused by the Workbook() type
annotations changes in v3.2.7 and v3.2.6.
:issue:1154.
Fixed typing issue in Workbook() constructor.
Fixed typing issue in Workbook() constructor.
:issue:1152.
Added an option to position custom data labels in the same way that the data labels can be positioned for the entire series.
Added an option to position custom data labels in the same way that the data labels can be positioned for the entire series.
:feature:1147.
Add border, fill, gradient and pattern formatting options for chart titles and also chart axis titles.
:feature:957.
Add additional type annotations. This is an ongoing refactoring.
:feature:1123.
Added an option to position custom data labels in the same way that the data labels can be positioned for the entire series.
Feature Request 1147 .
Add border, fill, gradient and pattern formatting options for chart titles and also chart axis titles.
Feature Request 957 .
Add additional type annotations. This is an ongoing refactoring.
Feature Request 1123 .
Fixed issue where a test function was made public incorrectly which caused warnings about a missing xlsxwriter.test module.
Fixed issue where a test function was made public incorrectly which caused
warnings about a missing xlsxwriter.test module.
:issue:1138.
Added support for a Color() type. This is backwards compatible with existing Html and named color string types but also adds support for theme colors.
Added support for a Color() type. This is backwards compatible with existing Html and named color string types but also adds support for theme colors. See also colors.
Fixed issue where write_url() dropped implicit support for generic URL types due to the refactoring into a Url type in the previous release.
Fixed issue where max_url_length parameter wasn't honored.
Fix for a breaking change in v3.2.1.
Fix for a breaking change in v3.2.1.
The Format class contained methods called set_font(), set_size() and
set_color() which were old internal testing alternatives for
set_font_name(), set_font_size() and set_font_color(). Since they
were intentionally internal methods they were removed as part of a general
refactoring in v3.2.1. However, the alternative method names had leaked out
into production code and the removal caused breaks in dependent code. These
methods have been reinstated to prevent inadvertent breakages but may be
removed in the future after an orderly deprecation. Users should update to the
documented method names.
This release drops support for Python 3.6 and 3.7, which are both EOL, in order to simplify the additions of type annotations. The minimum supported version of Python is now Python 3.8.
This release contains code with initial type annotations as part of an overall effort to add type annotations to the entire code base. It also contains internal refactoring of some pseudo-types, based on dicts, into actual enum or class types to allow stronger type checking. These will be rolled out in upcoming releases.
This is part of a modernization of the XlsxWriter code base, see "XlsxWriter
Roadmap v2" :feature:1128.
As part of the type annotation refactoring support was added for an explicit
Url type in addition to the implicit string URLs used in previous
versions. This isn't documented in this release.
Added support for checkboxes via the insert_checkbox() method.
Added support for checkboxes via the insert_checkbox() method.
Checkboxes are a new feature added to Excel in 2024. They are a way of displaying a boolean value as a checkbox in a cell. The underlying value is still an Excel TRUE/FALSE boolean value and can be used in formulas and in references.
See ex_checkbox.
Added support for checkboxes via the insert_checkbox() method.
Checkboxes are a new feature added to Excel in 2024 . They are a way of displaying a boolean value as a checkbox in a cell. The underlying value is still an Excel TRUE/FALSE boolean value and can be used in formulas and in references.
See Example: Inserting a checkbox in a Worksheet .
Added improvements to autofit().
Added improvements to autofit().
Added the optional max_width parameter to the autofit() method to work around the issue where the autofit width is too big.
Excel autofits very long strings up to limit of 1790 pixels/255 characters. This is often too wide to display on a single screen at normal zoom. As such the max_width parameter is provided to enable a smaller upper pixel limit for autofitting long strings. See autofit().
Added the cell_autofit_width utility function to allow users to calculate the auto-fit width for a cell value. This allows the user to implement their own auto-fit logic. See ex_autofit_manually.
This is the 10th anniversary release of XlsxWriter. Version 0.0.1 was released on February 17 2013. Since then there have been 167 releases, 25,000 li
This is the 10th anniversary release of XlsxWriter. Version 0.0.1 was released on February 17 2013. Since then there have been 167 releases, 25,000 lines of code, 1600 test cases, 700 pages of documentation, 71,000 users on GitHub, 50 contributors, 1000 closed issues and 150 million yearly downloads. Thanks to everyone who has contributed code, given feedback or just used the library.
Add embed_image() worksheet method to embed images in cells. This is equivalent to Excel's menu item to insert an image using the option to "Place in Cell". It scales images automatically to the dimensions of the cell.
This has been a frequently requested feature for people creating spreadsheets with images for product items. See also ex_embedded_images.
Fix issue where a horizontal alignment format was ignored if indentation was also set.
Add fix for errant XML tag in chart leader lines for non-Pie charts.
Add fix for errant XML tag in chart leader lines for non-Pie charts.
:issue:1019 and :feature:1012.
Add fix for errant XML tag in chart leader lines for non-Pie charts.
Issue 1019 and Feature Request 1012 .
Add support for formatting the data label in chart trendlines.
Add support for formatting the data label in chart trendlines.
:feature:750.
Add support for formatting the data label in chart trendlines.
Feature Request 750 .
Add the very_hidden() method to hide a worksheet. This is similar to the hide() method except that the worksheet cannot be unhidden in the the Excel u
Add the very_hidden() method to hide a worksheet. This is similar to the hide() method except that the worksheet cannot be unhidden in the the Excel user interface. The Excel worksheet "xlSheetVeryHidden" option can only be unset programmatically via VBA.
Added fixes for column formulas in tables that were overridden by table data and which also didn't take future functions into account.
Added support for chart leader lines for chart types other than Pie and Doughnut.
Added support for chart leader lines for chart types other than Pie and Doughnut.
:feature:1012.
Added support for chart leader lines for chart types other than Pie and Doughnut.
Feature Request 1012 .
Added support for adding signed VBA macros to workbooks via the add_signed_vba_project method. See Working with VBA Macros_.
Added support for adding signed VBA macros to workbooks via the add_signed_vba_project method. See Working with VBA Macros.
Added support for enabling the Excel "Show #N/A as an empty cell" chart option via the show_na_as_empty_cell method.
Added support for enabling the Excel "Show #N/A as an empty cell" chart option via the show_na_as_empty_cell method.
Added support for custom total formulas to worksheet tables.
Added support for custom total formulas to worksheet tables.
:feature:982.
Added support for custom total formulas to worksheet tables.
Feature Request 982 .
Added worksheet page break preview mode via set_pagebreak_view().
Added worksheet page break preview mode via set_pagebreak_view().
Add support for new Excel dynamic functions added in 2023.
Add support for new Excel dynamic functions added in 2023.
:issue:984.
Added support for adding a color to the invert_if_negative chart option.
:feature:854.
Minor fix for cell color issue.
Add documentation and examples on ewx_polars to demonstrate new Polars _ integration of XlsxWriter in write_excel()_.
Add documentation and examples on ewx_polars to demonstrate new Polars integration of XlsxWriter in write_excel().
Add fix for rare issue with duplicate number formats.
Add documentation and examples on Working with Polars and XlsxWriter to demonstrate new Polars integration of XlsxWriter in write_excel() .
Add fix for rare issue with duplicate number formats.
Fix for autofit() exception when user defined column width was None.
autofit() exception when user defined column width was None.Improved autofit algorithm to account for the additional width of autofilter and table dropdowns.
Improved autofit algorithm to account for the additional width of autofilter and table dropdowns.
Improved autofit take user defined column widths into account.
Autofit will now only update the width for an existing column if it is greater than the user defined value. This allows the user to pre-load a minimum column width.
Added simulated worksheet autofit method.
Added simulated worksheet autofit method.
Added OverlappingRange exception which is raised during Worksheet add_table() or merge_range() if the range overlaps an existing worksheet table or me
Added OverlappingRange exception which is raised during Worksheet add_table() or merge_range() if the range overlaps an existing worksheet table or merge range. This is a file corruption error in Excel. See exceptions.
848
Added OverlappingRange exception which is raised during Worksheet add_table() or merge_range() if the range overlaps an existing worksheet table or merge range. This is a file corruption error in Excel. See The Exceptions Class .
Issue 848
Roll up release of several minor fixes.
Roll up release of several minor fixes.
Drop support for EOL Python 3.4 and 3.5.
Added print_black_and_white worksheet method to set "Black and White" print options.
Added print_black_and_white worksheet method to set "Black and White" print options.
Added print_black_and_white() worksheet method to set “Black and White” print options.
Feature Request 862 .
Added set_top_left_cell worksheet method to position the first visible cell in a worksheet.
Added set_top_left_cell worksheet method to position the first visible cell in a worksheet.
Added set_top_left_cell() worksheet method to position the first visible cell in a worksheet.
Feature Request 837 .
Add python_requires version to setup.py to help pip find the correct matching version for Python 2 and 3.
From now bug fixes and new features will only be available for Python 3. The deprecation notice for Python 2 support in XlsxWriter has been in place s…
This is the last XlsxWriter release to support Python 2. From now bug fixes and new features will only be available for Python 3. The deprecation notice for Python 2 support in XlsxWriter has been in place since May 2020 and the Python community support for Python 2 ended in January 2020. Downloads of XlsxWriter for Python 2 is currently less than 6% of all downloads of the library, and decreasing month by month.
Python 2 users should still be able to install versions of XlsxWriter up to this release but not any releases afterwards.
:feature:720.
Added Description/Alt Text and Decorative accessibility options for charts, textboxes and buttons. These options were already available for images.
Added some performance improvements. Performance for larger files should be 5-10% better.
Added support for background images in worksheets. See set_background and ex_background.
Added support for background images in worksheets. See set_background and ex_background.
Added support for background images in worksheets. See set_background() and Example: Setting the Worksheet Background .
Added support for GIF image files (and in Excel 365, animated GIF files).
Added support for dynamic arrays and new Excel 365 functions like UNIQUE and FILTER. See write_dynamic_array_formula, formula_dynamic_arrays and ex_dy
Added support for dynamic arrays and new Excel 365 functions like UNIQUE and FILTER. See write_dynamic_array_formula, formula_dynamic_arrays and ex_dynamic_arrays.
Added constructor option "use_future_functions" to enable newer Excel "future" functions in Formulas. See formula_future, and the Workbook constructor.
Added support for dynamic arrays and new Excel 365 functions like UNIQUE and FILTER. See write_dynamic_array_formula() , Dynamic Array support and Example: Dynamic array formulas .
Added constructor option “use_future_functions” to enable newer Excel “future” functions in Formulas. See Formulas added in Excel 2010 and later , and the Workbook() constructor.
Added fix for issue for where a y_axis font rotation of 0 was ignored.
Added option to set row heights and column widths in pixels via the set_row_pixels and set_column_pixels methods.
Added option to set row heights and column widths in pixels via the set_row_pixels and set_column_pixels methods.
…greater than 59 days, in hours). This is a backward incompatible change. 731.
Added ability to add accessibility options "description" and "decorative" to images via insert_image. 768.
Added fix for datetime.timedelta values that exceed the Excel 1900 leap day (timedeltas greater than 59 days, in hours). This is a backward incompatible change. 731.
Added the worksheet read_only_recommended method to set the Excel "Read-only Recommended" option that is available when saving a file. 784.
Fixed issue where temp files used in constant_memory mode weren't closed/deleted if the workbook object was garbage collected. 764.
Fixed issue where pattern formats without colors were given a default black fill color. 790.
Added option to set a chart crossing to 'min' as well as the existing 'max' option. The 'min' option isn't available in the Excel interface but can be enabled via VBA. 773.
Fixed issue where custom chart data labels didn't inherit the position of the data labels in the series. 754.
Fixed issue where custom chart data labels didn't inherit the position of
the data labels in the series. :issue:754.
Added text alignment for textboxes. The existing options allowed the text area to be aligned but didn't offer control over the text within that area.
Added Python 3.9 to the test matrix.
Added the worksheet unprotect_range() method to allow ranges within a protected worksheet to be unprotected. 507.
Added the worksheet unprotect_range() method to allow ranges within a protected worksheet to be unprotected. 507.
There are now over 1500 test cases in the test suite, including 900 tests that compare the output from XlsxWriter, byte for byte, against test files created in Excel. This is to ensure the maximum possible compatibility with Excel.
Fixed issue where relative url links in images didn't work. 751.
Fixed issue where relative url links in images didn't work. 751.
Added use_zip64 as a constructor option. 745.
Added check, and warning, for worksheet tables with no data row. Either with or without a header row. 715 and 679.
Add a warning when the string length in write_rich_string() exceeds Excel's limit. 372.
Replaced internal MD5 digest used to check for duplicate images with a SHA256 digest to avoid issues on operating systems such as Red Hat in FIPS mode
749.Added ignore_errors() worksheet method to to allow Excel worksheet errors/warnings to be ignored in user defined ranges. See also ex_ignore_errors. 67
Added ignore_errors() worksheet method to to allow Excel worksheet errors/warnings to be ignored in user defined ranges. See also ex_ignore_errors. 678.
Added warning when closing a file more than once via close() to help avoid errors where a file is closed within a loop or at the wrong scope level.
Added ignore_errors() worksheet method to to allow Excel worksheet errors/warnings to be ignored in user defined ranges. See also Example: Ignoring Worksheet errors and warnings . Feature Request 678 .
Added warning when closing a file more than once via close() to help avoid errors where a file is closed within a loop or at the wrong scope level.
Added Border, Fill, Pattern and Gradient formatting to chart data labels and chart custom data labels. See chart_series_option_data_labels and chart_s
Added Border, Fill, Pattern and Gradient formatting to chart data labels and chart custom data labels. See chart_series_option_data_labels and chart_series_option_custom_data_labels.
Fix for issue where array formulas weren't included in the output file for certain ranges/conditions. 735.
735.Added support for chart custom data labels . 343.
Added support for chart custom data labels. 343.
Added support for stacked and percent_stacked Line charts.
stacked and percent_stacked Line charts.Fix for issue where duplicate images with hyperlinks weren't handled correctly. 686.
Fix for issue where duplicate images with hyperlinks weren't handled correctly. 686.
Removed ReservedWorksheetName exception which was used with the reserved worksheet name "History" since this name is allowed in some Excel variants. 688.
Fix for worksheet objects (charts, images and textboxes) that are inserted with an offset that starts in a hidden cell. 676.
Fix to allow handling of NoneType in add_write_handler. 677.
Fix for duplicate images being copied to an XlsxWriter file. Excel uses an optimization where it only stores one copy of a repeated/duplicate image in
Fix for duplicate images being copied to an XlsxWriter file. Excel uses an optimization where it only stores one copy of a repeated/duplicate image in a workbook. XlsxWriter didn't do this which meant that the file size would increase when then was a large number of repeated images. This release fixes that issue and replicates Excel's behavior. 615.
Added documentation on num_format_categories and num_format_locale.
Added note to protect() about how it is possible to encrypt an XlsxWriter file using a third party, cross platform, open source tool called msoffice-crypt.
Fix for duplicate images being copied to an XlsxWriter file. Excel uses an optimization where it only stores one copy of a repeated/duplicate image in a workbook. XlsxWriter didn’t do this which meant that the file size would increase when then was a large number of repeated images. This release fixes that issue and replicates Excel’s behavior. Issue 615 .
Added documentation on Number Format Categories and Number Formats in different locales .
Added note to protect() about how it is possible to encrypt an XlsxWriter file using a third party, cross platform, open source tool called msoffice-crypt .
Added option to remove style from worksheet tables. 670.
670.Added option to remove style from worksheet tables. Feature Request 670 .
Added option to add hyperlinks to textboxes. See textbox_hyperlink. 419.
Added option to add hyperlinks to textboxes. See textbox_hyperlink. 419.
Added option to add hyperlinks to textboxes. See Textbox Hyperlink . Feature Request 419 .
Added option to link textbox text from a cell. See textbox_textlink. 516.
Added option to link textbox text from a cell. See textbox_textlink. 516.
Added option to rotate text in a textbox. See textbox_formatting_rotation. 638.
Added option to link textbox text from a cell. See Textbox Textlink . Feature Request 516 .
Added option to rotate text in a textbox. See Textbox formatting: Text Rotation . Feature Request 638 .
Increased allowable worksheet url length from 255 to 2079 characters, as supported in more recent versions of Excel. A lower or user defined limit can
Increased allowable worksheet url length from 255 to 2079 characters, as supported in more recent versions of Excel. A lower or user defined limit can be set via the max_url_length property in the Workbook constructor.
Fixed several issues with hyperlinks in worksheet images.
Fixed Python 3.8.0 warnings. 660.
660.Added the add_write_handler method to allow user defined types to be handled by the write method. See writing_user_types for more information. 631.
Added the add_write_handler method to allow user defined types to be handled by the write method. See writing_user_types for more information. 631.
Add support for East Asian vertical fonts in charts. 648.
Added the add_write_handler() method to allow user defined types to be handled by the write() method. See Writing user defined types for more information. Feature Request 631 .
Add support for East Asian vertical fonts in charts. Feature Request 648 .
One column per quarter.