{"id":597,"library":"xlrd","title":"xlrd","description":"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.","status":"maintenance","version":"2.0.2","language":"python","source_language":"en","source_url":"https://github.com/python-excel/xlrd","tags":["excel","spreadsheet","xls","data extraction","parser"],"install":[{"cmd":"pip install xlrd","lang":"bash","label":"Install xlrd"}],"dependencies":[],"imports":[{"symbol":"open_workbook","correct":"import xlrd\nworkbook = xlrd.open_workbook('myfile.xls')"}],"quickstart":{"code":"import xlrd\nimport os\n\n# --- IMPORTANT NOTE ---\n# xlrd *only* reads .xls files (Excel 97-2003 format) as of version 2.0.0.\n# This example assumes 'example.xls' exists and is a valid .xls file.\n# For .xlsx files (Excel 2007+), use a library like 'openpyxl'.\n# ----------------------\n\nfile_path = \"example.xls\" # Replace with your .xls file path\n\ntry:\n    # Open the workbook\n    book = xlrd.open_workbook(file_path)\n\n    print(f\"Successfully opened '{file_path}'.\")\n\n    # Print number of sheets\n    print(f\"The number of worksheets is: {book.nsheets}\")\n\n    # Print sheet names\n    print(f\"Worksheet name(s): {book.sheet_names()}\")\n\n    # Get the first sheet by index (0-indexed)\n    sh = book.sheet_by_index(0)\n\n    # Print sheet details\n    print(f\"\\nSheet '{sh.name}' details:\")\n    print(f\"  Rows: {sh.nrows}\")\n    print(f\"  Columns: {sh.ncols}\")\n\n    # Read a cell value (e.g., cell at row index 0, column index 0)\n    if sh.nrows > 0 and sh.ncols > 0:\n        cell_value = sh.cell_value(rowx=0, colx=0)\n        print(f\"  Value of cell (0,0): {cell_value}\")\n    else:\n        print(\"  Sheet is empty or does not have cell (0,0).\")\n\n    # Iterate over rows and print values (first 3 rows for brevity)\n    print(\"\\nFirst 3 rows of data (or fewer if sheet has less):\")\n    for rx in range(min(sh.nrows, 3)):\n        print(f\"  Row {rx}: {sh.row_values(rx)}\")\n\nexcept FileNotFoundError:\n    print(f\"Error: The file '{file_path}' was not found.\")\n    print(\"Please ensure a valid 'example.xls' file exists in the specified path.\")\nexcept xlrd.XLRDError as e:\n    print(f\"Error opening Excel file: {e}\")\n    print(\"Please ensure the file is a valid .xls (Excel 97-2003) format.\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")","lang":"python","description":"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`."},"warnings":[{"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.","message":"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`.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Use dedicated libraries like `xlwt` (for `.xls`) or `openpyxl` (for `.xlsx`) for writing Excel files.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"The file must be un-protected manually before `xlrd` can read it.","message":"Password-protected Excel files cannot be read by `xlrd`. The library does not provide functionality to decrypt or bypass password protection.","severity":"gotcha","affected_versions":"All versions"},{"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)`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always install `openpyxl` (`pip install openpyxl`) when working with `.xlsx` files via `pandas.read_excel`. This ensures `pandas` uses the correct engine.","message":"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`.","severity":"gotcha","affected_versions":"xlrd >= 2.0.0, pandas versions that rely on `xlrd` for `.xlsx` if `openpyxl` is absent."},{"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.","message":"The 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.","severity":"breaking","affected_versions":"All versions"},{"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.","message":"The 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.","severity":"breaking","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-05-12T16:25:39.719Z","next_check":"2026-06-26T00:00:00.000Z","problems":[{"fix":"Use the `openpyxl` library to read and write .xlsx files, or downgrade `xlrd` to version 1.2.0 if legacy .xlsx support is essential (not recommended).","cause":"The user is attempting to open an Excel 2007+ (.xlsx) file with xlrd version 2.0.0 or later, which explicitly dropped support for these files.","error":"XLRDError: Excel 2007+ (xlsx) files are not supported"},{"fix":"Ensure the file is a genuine and uncorrupted Excel 97-2003 (.xls) format file; use `openpyxl` for .xlsx files or `pandas.read_csv()` for CSVs.","cause":"The file provided to `xlrd.open_workbook()` is not a valid Excel 97-2003 (.xls) file, is corrupt, or is a different file type (e.g., CSV, HTML) incorrectly named with a .xls extension.","error":"XLRDError: Unsupported format, or corrupt file: Expected BOF record; found '...'"},{"fix":"Install the library using pip: `pip install xlrd`","cause":"The `xlrd` library has not been installed in the Python environment where the code is being executed.","error":"ModuleNotFoundError: No module named 'xlrd'"},{"fix":"Use the `xlwt` library for writing .xls files or the `openpyxl` library for writing .xlsx files.","cause":"`xlrd` is a read-only library and does not provide methods to save or write changes to Excel files.","error":"AttributeError: 'Book' object has no attribute 'save'"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":80,"quickstart_tag":"verified","pypi_latest":"2.0.2","install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.05,"mem_mb":3.1,"disk_size":"18.4M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.06,"mem_mb":3.1,"disk_size":"18.4M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.5,"import_time_s":0.04,"mem_mb":3.1,"disk_size":"19M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.03,"mem_mb":3.1,"disk_size":"19M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.09,"mem_mb":3.7,"disk_size":"20.3M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.1,"mem_mb":3.7,"disk_size":"20.3M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.6,"import_time_s":0.07,"mem_mb":3.7,"disk_size":"21M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.07,"mem_mb":3.7,"disk_size":"21M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.09,"mem_mb":3.4,"disk_size":"12.2M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.1,"mem_mb":3.4,"disk_size":"12.2M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.5,"import_time_s":0.09,"mem_mb":3.4,"disk_size":"13M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.09,"mem_mb":3.4,"disk_size":"13M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.09,"mem_mb":3.9,"disk_size":"11.9M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.09,"mem_mb":3.7,"disk_size":"11.8M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.5,"import_time_s":0.09,"mem_mb":3.9,"disk_size":"12M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.08,"mem_mb":3.5,"disk_size":"12M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":2.3,"disk_size":"17.9M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":2.3,"disk_size":"17.9M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.8,"import_time_s":0.03,"mem_mb":2.3,"disk_size":"18M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.03,"mem_mb":2.3,"disk_size":"18M"}]},"quickstart_checks":{"last_tested":"2026-04-23","tag":"verified","tag_description":"quickstart runs on critical runtimes, recently tested","results":[{"runtime":"python:3.10-alpine","exit_code":0},{"runtime":"python:3.10-slim","exit_code":0},{"runtime":"python:3.11-alpine","exit_code":0},{"runtime":"python:3.11-slim","exit_code":0},{"runtime":"python:3.12-alpine","exit_code":0},{"runtime":"python:3.12-slim","exit_code":0},{"runtime":"python:3.13-alpine","exit_code":0},{"runtime":"python:3.13-slim","exit_code":0},{"runtime":"python:3.9-alpine","exit_code":0},{"runtime":"python:3.9-slim","exit_code":0}]}}