xlrd

Warnings

• breaking As of `xlrd` version 2.0.0, support for `.xlsx` files was entirely removed. Attempting to open an `.xlsx` file will result in an `xlrd.XLRDError: Excel xlsx file; not supported`.
  Fix: For reading `.xlsx` files (Excel 2007+), use the `openpyxl` library instead. If using `pandas.read_excel`, ensure `openpyxl` is installed so pandas can automatically choose the correct engine for `.xlsx` files.
• gotcha xlrd is strictly a *reader* library; it does not support writing to Excel files. For writing to `.xls` files, consider `xlwt`. For `.xlsx` files, `openpyxl` is the standard.
  Fix: Use dedicated libraries like `xlwt` (for `.xls`) or `openpyxl` (for `.xlsx`) for writing Excel files.
• gotcha Password-protected Excel files cannot be read by `xlrd`. The library does not provide functionality to decrypt or bypass password protection.
  Fix: The file must be un-protected manually before `xlrd` can read it.
• gotcha By default, `xlrd.open_workbook()` does *not* load formatting information (e.g., cell colors, fonts, borders) to save memory. Blank cells (cells with formatting but no data) are ignored.
  Fix: To enable reading formatting information, pass `formatting_info=True` to `xlrd.open_workbook()`. Be aware that this can significantly increase memory usage, especially for large files. `book = xlrd.open_workbook('myfile.xls', formatting_info=True)`.
• gotcha Many advanced Excel features are explicitly ignored or only partially supported. This includes Charts, Macros, Pictures, VBA modules, Comments, Hyperlinks, Autofilters, Pivot Tables, Conditional Formatting, and Data Validation. Formulas are read, but only their calculated results, not the formula text itself.
  Fix: If these specific features are crucial, `xlrd` may not be the appropriate tool. Consider using COM automation (Windows-only) or commercial libraries that offer more comprehensive Excel interaction.
• gotcha When using `pandas.read_excel` with `.xlsx` files, pandas typically tries `openpyxl` first. However, if `openpyxl` is not installed and `xlrd` (version >= 2.0.0) is the only Excel engine available, `pandas` will raise an error because `xlrd` no longer supports `.xlsx`.
  Fix: Always install `openpyxl` (`pip install openpyxl`) when working with `.xlsx` files via `pandas.read_excel`. This ensures `pandas` uses the correct engine.

Install

• pip install xlrd Install xlrd

Imports

• open_workbook

  import xlrd
  workbook = xlrd.open_workbook('myfile.xls')

Quickstart

This quickstart demonstrates how to open an existing `.xls` workbook, access its sheets, and read cell values. Remember, `xlrd` only supports the `.xls` format (Excel 97-2003) as of version 2.0.0. For newer `.xlsx` files, consider `openpyxl`.

import xlrd
import os

# --- IMPORTANT NOTE ---
# xlrd *only* reads .xls files (Excel 97-2003 format) as of version 2.0.0.
# This example assumes 'example.xls' exists and is a valid .xls file.
# For .xlsx files (Excel 2007+), use a library like 'openpyxl'.
# ----------------------

file_path = "example.xls" # Replace with your .xls file path

try:
    # Open the workbook
    book = xlrd.open_workbook(file_path)

    print(f"Successfully opened '{file_path}'.")

    # Print number of sheets
    print(f"The number of worksheets is: {book.nsheets}")

    # Print sheet names
    print(f"Worksheet name(s): {book.sheet_names()}")

    # Get the first sheet by index (0-indexed)
    sh = book.sheet_by_index(0)

    # Print sheet details
    print(f"\nSheet '{sh.name}' details:")
    print(f"  Rows: {sh.nrows}")
    print(f"  Columns: {sh.ncols}")

    # Read a cell value (e.g., cell at row index 0, column index 0)
    if sh.nrows > 0 and sh.ncols > 0:
        cell_value = sh.cell_value(rowx=0, colx=0)
        print(f"  Value of cell (0,0): {cell_value}")
    else:
        print("  Sheet is empty or does not have cell (0,0).")

    # Iterate over rows and print values (first 3 rows for brevity)
    print("\nFirst 3 rows of data (or fewer if sheet has less):")
    for rx in range(min(sh.nrows, 3)):
        print(f"  Row {rx}: {sh.row_values(rx)}")

except FileNotFoundError:
    print(f"Error: The file '{file_path}' was not found.")
    print("Please ensure a valid 'example.xls' file exists in the specified path.")
except xlrd.XLRDError as e:
    print(f"Error opening Excel file: {e}")
    print("Please ensure the file is a valid .xls (Excel 97-2003) format.")
except Exception as e:
    print(f"An unexpected error occurred: {e}")