Install & Compatibility
Where this runs
tested against v16.5.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.910 runs
build_error
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 3.6s · import 0.775s · 145MB
144MB installed
● package 144MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Workbook
✓ from spire.xls import Workbook
FileFormat
✓ from spire.xls import FileFormat
Used for specifying file types during operations.
SaveFormat
✓ from spire.xls import SaveFormat
Used for specifying output file formats when saving.
This quickstart demonstrates how to create a new Excel workbook, write data to cells using A1 notation, auto-fit columns, and save the workbook as an XLSX file. The `Dispose()` method is called to release resources.
from spire.xls import Workbook, SaveFormat
# Create a new workbook
workbook = Workbook()
# Access the first worksheet (0-indexed)
sheet = workbook.Worksheets[0]
# Write data to cells using A1 notation
sheet.Range["A1"].Value = "Hello, Spire.XLS!"
sheet.Range["B1"].Value2 = 12345
# Auto-fit columns
sheet.AllocatedRange.AutoFitColumns()
# Define the output file path
output_file = "output_spire_xls_quickstart.xlsx"
# Save the workbook in XLSX format
workbook.SaveToFile(output_file, SaveFormat.Xlsx)
workbook.Dispose()
print(f"Excel file saved to {output_file}")
Debug
Known issues
breakingThe free evaluation version of Spire.XLS for Python has significant limitations. It restricts operations to a maximum of 500 rows and 5 worksheets per Excel file (for both loading and saving). Exceeding these limits will raise an exception.fixEnsure your Excel processing stays within the free evaluation limits (500 rows, 5 worksheets) or purchase a commercial license for full functionality.
affects: All versions with a free evaluation tier.
gotchaProcessing very large Excel files (e.g., hundreds of thousands of rows or complex formatting) can lead to high memory consumption, as the library often loads the entire document into memory.fixFor extremely large files, consider optimizing your logic to process data in chunks if applicable, or ensure your execution environment has sufficient RAM.
affects: All versions.
gotchaWhile `sheet.Range["A1"]` uses Excel's 1-based A1 notation, direct access to collection elements like `sheet.Worksheets`, `sheet.Rows`, and `sheet.Columns` uses 0-based indexing common in Python.fixBe mindful of the indexing scheme (0-based vs. 1-based) depending on whether you're using `Range["A1"]` strings or direct collection access.
affects: All versions.
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'spire'
The `spire-xls` package is not installed in the active Python environment or the environment is not correctly activated.
fixInstall the package using `pip install spire-xls` in your project's virtual environment or global environment.
System.ArgumentException: The free version of Spire.XLS for Python has a limitation of 500 rows and 5 worksheets for opening and writing.
You are attempting to process an Excel file that exceeds the row or worksheet limits imposed by the free evaluation version of Spire.XLS for Python.
fixEither reduce the size/complexity of the Excel files you are processing to fit within the 500-row/5-worksheet limit, or acquire and activate a commercial license from e-iceblue.
AttributeError: 'Worksheet' object has no attribute 'Range'
You are attempting to call `Range` as a method (e.g., `sheet.Range("A1")`) when it is an indexer property.
fixAccess cells using bracket notation for the `Range` property, e.g., `sheet.Range["A1"].Value = "data"`.
System.ArgumentException: SaveFormat.Xls does not match the file extension .xlsx.
There is a mismatch between the `SaveFormat` enumeration value provided to `SaveToFile` and the file extension specified in the output file path.
fixEnsure the `SaveFormat` enum matches the file extension. Use `SaveFormat.Xlsx` for `.xlsx` files and `SaveFormat.Xls` for `.xls` files.
Upgrade
Version history
16.5.0latest on PyPI · released May 7, 2026
Audit
Dependencies
No dependency data recorded yet.