Install & Compatibility
Where this runs
tested against v0.2.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
installs and imports cleanly · install 0.0s · import 1.663s · 73.9MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 5.1s · import 1.548s · 79MB
77MB installed
● package 77MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
XLS2XLSX
✓ from xls2xlsx import XLS2XLSX
This quickstart demonstrates how to convert an `.xls` file to `.xlsx`. It first creates a dummy `.xls` file using `xlwt` (which needs to be installed separately via `pip install xlwt` to make the example runnable out-of-the-box) and then performs the conversion, verifying the output before cleaning up the temporary files.
import os
from xls2xlsx import XLS2XLSX
input_file = "temp_input.xls"
output_file = "temp_output.xlsx"
# --- Create a dummy .xls file for demonstration ---
# This part requires 'xlwt' to be installed (pip install xlwt).
# If xlwt is not installed, the example will print an error
# and not proceed with the conversion.
try:
import xlwt
workbook = xlwt.Workbook()
sheet = workbook.add_sheet("Sheet1")
sheet.write(0, 0, "Hello")
sheet.write(0, 1, "World")
sheet.write(1, 0, 123)
sheet.write(1, 1, 456)
workbook.save(input_file)
print(f"Created dummy input file: {input_file}")
except ImportError:
print("Error: 'xlwt' library not found. Please install it (pip install xlwt) to run this quickstart, or create 'temp_input.xls' manually.")
exit(1) # Exit if we cannot create the prerequisite file
# --- Perform the conversion ---
try:
print(f"Converting '{input_file}' to '{output_file}'...")
x2x = XLS2XLSX(input_file)
x2x.to_xlsx(output_file)
print(f"Conversion complete. Output saved to '{output_file}'.")
# --- Optional: Verify the output (requires openpyxl, a core dependency) ---
import openpyxl
wb_xlsx = openpyxl.load_workbook(output_file)
sheet_xlsx = wb_xlsx.active
print(f"Verifying content: A1='{sheet_xlsx['A1'].value}', B1='{sheet_xlsx['B1'].value}'")
assert sheet_xlsx['A1'].value == "Hello"
assert sheet_xlsx['B1'].value == "World"
print("Verification successful.")
except FileNotFoundError:
print(f"Error: Input file '{input_file}' not found. Please ensure it exists.")
except Exception as e:
print(f"An error occurred during conversion: {e}")
finally:
# --- Clean up dummy files ---
print("Cleaning up temporary files...")
if os.path.exists(input_file):
os.remove(input_file)
if os.path.exists(output_file):
os.remove(output_file)
print("Cleanup complete.")
Debug
Known issues
breakingCritical: `xlrd` Version Compatibility for .xls support. `xls2xlsx` relies on `xlrd` to read `.xls` files. `xlrd` versions 2.0.0 and above intentionally removed support for `.xls` files by default to focus on `.xlsx`. If `xlrd>=2.0.0` is installed in your environment, `xls2xlsx` will fail to open `.xls` files, even though `xls2xlsx`'s `setup.py` allows it. This is a common footgun for users who install the latest `xlrd`.fixEnsure `xlrd` is downgraded to a version less than 2.0.0, e.g., by running `pip install "xlrd<2.0.0"`.
affects: xls2xlsx 0.1.0 to 0.2.0 when used with `xlrd>=2.0.0`.
gotchaPerformance and Memory Usage for Large Files. Converting very large `.xls` files can be memory-intensive. `xlrd` typically loads the entire workbook into memory, which can lead to high RAM consumption and slow performance for multi-megabyte or gigabyte files.fixFor extremely large files, consider processing in chunks if possible (though `xls2xlsx` does not directly support this), or use alternative tools designed for streaming large datasets. Ensure sufficient RAM is available for conversion.
affects: All versions of `xls2xlsx`.
gotchaFeature Loss (Macros, Charts, Complex Formatting). The `.xls` to `.xlsx` conversion primarily focuses on data and basic formatting. Complex features such as VBA macros, charts, embedded objects, custom views, and certain advanced cell styles or formulas may not be fully preserved or may be lost during the conversion.fixManually inspect converted `.xlsx` files for fidelity, especially for spreadsheets containing advanced features. Be prepared to recreate complex elements in the `.xlsx` file if necessary.
affects: All versions of `xls2xlsx`.
gotchaLibrary Maintenance Status. The `xls2xlsx` library appears to be in maintenance mode, with its last release (0.2.0) in March 2021. This indicates that new features, performance improvements, or prompt bug/security fixes are unlikely. Users should be aware that the project is not actively developed.fixFor critical long-term projects, evaluate the stability and current features carefully. If new features or active maintenance are required, consider alternative libraries or be prepared to maintain a fork.
affects: All versions (0.1.0-0.2.0).
Upgrade
Version history
0.2.0latest on PyPI · released Jan 6, 2023
Audit
Dependencies
xlrdrequiredRequired for reading .xls files. Note critical compatibility warning regarding xlrd versions >= 2.0.0.
openpyxlrequiredRequired for writing .xlsx files.
Resources
No resource links recorded.