XLS to XLSX File Converter

Warnings

• breaking Critical: `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`.
  Fix: Ensure `xlrd` is downgraded to a version less than 2.0.0, e.g., by running `pip install "xlrd<2.0.0"`.
• gotcha Performance 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.
  Fix: For 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.
• gotcha Feature 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.
  Fix: Manually inspect converted `.xlsx` files for fidelity, especially for spreadsheets containing advanced features. Be prepared to recreate complex elements in the `.xlsx` file if necessary.
• gotcha Library 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.
  Fix: For 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.

Install

• pip install xls2xlsx Install xls2xlsx

Imports

• XLS2XLSX

  from xls2xlsx import XLS2XLSX

Quickstart

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.")