Install & Compatibility
Where this runs
tested against v2.0.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.144s · 19.7MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.7s · import 0.130s · 20MB
18MB installed
● package 18MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
copy
✓ from xlutils.copy import copy
The primary utility for copying xlrd.Book objects to xlwt.Workbook objects for modification.
XLRDReader
✓ from xlutils.filter import process, XLRDReader, XLWTWriter
Used in conjunction with `XLWTWriter` and `process` for advanced filtering and style preservation.
This quickstart demonstrates how to use `xlutils.copy` to open an existing Excel file (in `.xls` format), make modifications to a cell, and save the changes to a new file. It first creates a dummy `.xls` file to ensure the example is runnable. `formatting_info=True` is crucial for attempting to preserve styles during the copy operation.
import xlrd
import xlwt
from xlutils.copy import copy
# Create a dummy .xls file first for demonstration
wb_initial = xlwt.Workbook()
ws_initial = wb_initial.add_sheet('Sheet1')
ws_initial.write(0, 0, 'Hello')
ws_initial.write(0, 1, 'World')
ws_initial.write(1, 0, 'Original Value')
wb_initial.save('example_input.xls')
# Open the existing workbook with xlrd
rb = xlrd.open_workbook('example_input.xls', formatting_info=True)
# Make a writable copy of the workbook using xlutils.copy
wb = copy(rb)
# Get the first sheet from the copied workbook
ws = wb.get_sheet(0)
# Write a new value to a cell (e.g., cell B2)
ws.write(1, 1, 'Modified Value')
# Save the modified workbook to a new .xls file
wb.save('example_output.xls')
print("Modified workbook saved as 'example_output.xls'")
# Clean up dummy file (optional)
import os
os.remove('example_input.xls')
os.remove('example_output.xls')
Debug
Known issues
breakingxlrd version 2.0.0 and later no longer supports `.xlsx` files due to security vulnerabilities related to parsing. Since `xlutils` relies on `xlrd` for reading, it is effectively limited to `.xls` files for input. Attempting to open an `.xlsx` file will result in an error.fixEnsure input files are in `.xls` format. For `.xlsx` files, consider migrating to `openpyxl`.
affects: xlrd >= 2.0.0 (and thus xlutils using this version or later)
deprecatedxlutils, xlrd, and xlwt are largely unmaintained or in archive status on GitHub. `xlrd` itself advises users to use `openpyxl` for modern Excel file formats (`.xlsx`). It is recommended to use `openpyxl` for new projects or when working with `.xlsx` files.fixFor new projects, prefer `openpyxl`. For existing projects using `xlutils` and requiring `.xlsx` support, consider migrating.
affects: All versions
gotchaDirectly copying cell style information from an `xlrd.Book` object to an `xlwt.Workbook` object is complex. `xlrd` and `xlwt` use different internal representations for cell formatting (`XF` objects). While `xlutils.copy` attempts to preserve basic formatting, detailed style manipulation often requires using `xlutils.filter` with custom logic or a specific workaround.fixFor precise style preservation or modification, refer to `xlutils.filter` documentation or community solutions, often involving `XLRDReader` and `XLWTWriter`.
affects: All versions
gotchaWhen writing to an Excel sheet using `xlwt` (and by extension `xlutils.copy`), column indices are limited to a range of 0-255 (corresponding to columns A through IV in Excel 2003 `.xls` format). Attempting to write to a column index outside this range will raise a `ValueError`.fixEnsure column indices are within the valid range (0-255). If more columns are needed, consider using a library like `openpyxl` that supports newer `.xlsx` formats with larger sheet dimensions.
affects: All versions (due to underlying xlwt limitations)
Errors
Common errors & fixes
xlrd.biffh.XLRDError: Unsupported format, or corrupt file: Saw 0x00000000000000000000000000000000 but expected 0x0002000000000600
`xlutils` (and its underlying dependency `xlrd`) is designed exclusively for the older `.xls` (BIFF) file format and cannot process newer `.xlsx` (OOXML) files.
fixUse a library specifically designed for `.xlsx` files, such as `openpyxl`, instead of `xlutils`.
ValueError: row index must be less than 65536
The `.xls` file format, which `xlutils` utilizes via `xlwt` for writing, has a strict limit of 65,536 rows per worksheet.
fixFor datasets exceeding 65,536 rows, you must switch to the `.xlsx` format and use a library like `openpyxl`.
ModuleNotFoundError: No module named 'xlutils'
The `xlutils` package has not been installed in your current Python environment.
fixInstall the package using pip: `pip install xlutils`
NotImplementedError: formatting_info=True not yet implemented for .xls files
`xlutils` operations that preserve or access cell formatting rely on `xlrd`'s `formatting_info` functionality, which was removed for security reasons in `xlrd` versions 2.0.0 and newer.
fixDowngrade your `xlrd` installation to a version prior to 2.0.0 (e.g., `pip install xlrd==1.2.0`) or avoid `xlutils` operations that require reading or copying formatting information.
Upgrade
Version history
2.0.0latest on PyPI · released Jun 9, 2016
Audit
Dependencies
xlrdrequiredRequired for reading Excel files. Version 0.6.1a1 or later.
xlwtrequiredRequired for writing Excel files. Version 0.7.0 or later.
errorhandleroptionalRequired only if using xlutils.filter.ErrorFilter.