Registry / data / xlrd
library2.0.2pypypi✓ verified 26d ago

xlrd is a Python library for reading data and formatting information from older Microsoft Excel `.xls` spreadsheet files (Excel 97-2003 format). As of version 2.0.0, it explicitly ceased support for `.xlsx` files due to security concerns and unreliability. The current version is 2.0.2, and it follows an infrequent, needs-based release cadence, primarily for maintenance of `.xls` support.

pip install xlrd
INSTALL
IMPORT
SIG · XLRD
X
xlrd
datapythonv2.0.2
Install
1.7s avg
Import
73ms
Disk
16MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
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
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.078s · 18.4MB
glibc
py 3.103.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`.
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.
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.
fix
Use 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.
fix
The 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.
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)`.
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.
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.
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`.
fix
Always 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.
fix
Ensure 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.
fix
Ensure 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.

Agent activity
85 hits · last 30 days
node
76
panscient.com
1
OpenAI (training)
1
Resources
xlrd — pip install xlrd · libregistry