Install & Compatibility
Where this runs
tested against v2.0.0.20260518 · 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.070s · 18.5MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.7s · import 0.064s · 19MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
open_workbook
✓ import xlrd; xlrd.open_workbook
Book
✓ from xlrd.book import Book
Sheet
✓ from xlrd.sheet import Sheet
XLRDError
✓ from xlrd.biffh import XLRDError
This quickstart demonstrates how to open an Excel `.xls` file, access a specific sheet, read individual cell values, and iterate through all cells in the sheet using `xlrd`. It includes basic error handling for file not found or incorrect file format. Users must provide an existing `.xls` file.
import xlrd
import os
# Create a dummy .xls file for demonstration if it doesn't exist
# In a real scenario, you would open an existing .xls file
xls_file_path = 'example.xls'
if not os.path.exists(xls_file_path):
# This part requires an actual .xls file or a library to create one (e.g., xlwt)
# For a runnable example without xlwt, we'll simulate opening.
# In practice, ensure 'example.xls' is a valid Excel 97-2003 file.
print(f"Please create a dummy Excel 97-2003 (.xls) file named '{xls_file_path}' with some data.")
print("For example, put 'Hello' in A1 and 'World' in B1 of Sheet1.")
# For this quickstart, we'll proceed assuming the file exists
# and will raise an error if not, which is expected for `xlrd`.
try:
# Open the workbook (assumes example.xls exists and is an .xls file)
book: xlrd.Book = xlrd.open_workbook(xls_file_path)
# Get the first sheet by index
sheet: xlrd.sheet.Sheet = book.sheet_by_index(0)
# Read a cell value (e.g., A1, which is (0, 0))
cell_value: str = sheet.cell_value(0, 0)
print(f"Value from cell A1: {cell_value}")
# Iterate through rows and print values
print("\nAll values in the first sheet:")
for row_idx in range(sheet.nrows):
for col_idx in range(sheet.ncols):
cell = sheet.cell(row_idx, col_idx)
print(f"({row_idx}, {col_idx}): {cell.value}", end="\t")
print()
except xlrd.biffh.XLRDError as e:
print(f"Error opening Excel file: {e}")
print("Make sure 'example.xls' is a valid Excel 97-2003 (.xls) file.")
except FileNotFoundError:
print(f"Error: The file '{xls_file_path}' was not found. Please create it.")
Debug
Known issues
breakingSince `xlrd` version 2.0.0, the library *no longer supports reading `.xlsx` (Excel 2007 and later) files*. It strictly reads only the older `.xls` (Excel 97-2003 Workbook) format. Attempting to open an `.xlsx` file will result in an `xlrd.biffh.XLRDError: Excel xlsx file; not supported` error.fixFor `.xlsx` files, use the `openpyxl` library instead. If using `pandas.read_excel`, specify `engine='openpyxl'` (e.g., `pd.read_excel('file.xlsx', engine='openpyxl')`) after installing `openpyxl`. affects: xlrd >= 2.0.0
gotcha`xlrd` has limited functionality and does not support many advanced Excel features. Specifically, it will safely ignore or not extract information about Charts, Macros, Pictures, embedded objects (including worksheets), VBA modules, Comments, Hyperlinks, Autofilters, Advanced Filters, Pivot Tables, Conditional Formatting, Data Validation, and password-protected files. Only the results of formula calculations are extracted, not the formulas themselves.fixBe aware of these limitations. For operations requiring more comprehensive interaction with Excel features or writing to `.xls` files, consider using `openpyxl` (for `.xlsx` and some `.xls` features) or `xlwt` (for writing `.xls` files).
affects: All versions
gotchaThe `types-xlrd` package from `typeshed` requires Python >=3.10 for its stubs. While older versions of the `xlrd` library might have supported earlier Python versions (e.g., Python 2.7+ to 3.6+ for `xlrd < 2.0.0`), using `types-xlrd` implies a modern Python environment. Ensure your runtime Python version meets this requirement, especially if you are using `mypy` or other type checkers.fixEnsure your project's Python interpreter is version 3.10 or newer if you intend to use `types-xlrd` for type checking.
affects: types-xlrd >= 2.0.0.x
Upgrade
Version history
2.0.0.20260518latest on PyPI · released May 18, 2026
Audit
Dependencies
xlrdrequiredThese are typing stubs for the `xlrd` library; `xlrd` must be installed for runtime functionality.