Install & Compatibility
Where this runs
tested against v2.0.2 · 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.078s · 18.4MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.7s · import 0.068s · 19MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
open_workbook
✓ from xlrd import open_workbook
✗ import xlrd
workbook = xlrd.open_workbook('myfile.xls')
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}")
Debug
Known issues
breakingAs 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`.fixFor 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.
affects: >=2.0.0
gotchaxlrd 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.fixUse dedicated libraries like `xlwt` (for `.xls`) or `openpyxl` (for `.xlsx`) for writing Excel files.
affects: All versions
gotchaPassword-protected Excel files cannot be read by `xlrd`. The library does not provide functionality to decrypt or bypass password protection.fixThe file must be un-protected manually before `xlrd` can read it.
affects: All versions
gotchaBy 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.fixTo 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)`. affects: All versions
gotchaMany 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.fixIf 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.
affects: All versions
gotchaWhen 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`.fixAlways install `openpyxl` (`pip install openpyxl`) when working with `.xlsx` files via `pandas.read_excel`. This ensures `pandas` uses the correct engine.
affects: xlrd >= 2.0.0, pandas versions that rely on `xlrd` for `.xlsx` if `openpyxl` is absent.
breakingThe specified Excel file could not be found. This typically means the file does not exist at the given path, or the path is incorrect. `xlrd` cannot process files that are not accessible.fixEnsure the Excel file exists in the expected location and the path provided to `xlrd.open_workbook()` is correct and accessible by the application. Double-check file name, extension, and directory.
affects: All versions
breakingThe specified Excel file was not found at the given path. This error occurs when the file either does not exist, is in a different location, or the application lacks the necessary permissions to access it.fixEnsure the file exists at the specified path. Verify the file name and path for any typos. Confirm that the application has the correct read permissions for the file and its containing directory. If the file is expected to be generated, check upstream processes.
affects: All versions
Upgrade
Version history
2.0.2latest on PyPI · released Jun 14, 2025
Audit
Dependencies
No dependency data recorded yet.