{"id":5542,"library":"types-xlrd","title":"Typing stubs for xlrd","description":"types-xlrd provides static type checking stubs for the `xlrd` library. `xlrd` is a Python library designed for reading data and formatting information from older Microsoft Excel `.xls` files (Excel 97-2003 Workbook format). The core `xlrd` library is currently at version 2.0.2 and has a stable release cadence, primarily focusing on bug fixes and maintaining `.xls` parsing functionality. The `types-xlrd` package aligns with the `xlrd` library's API for type hinting purposes.","status":"active","version":"2.0.0.20260408","language":"en","source_language":"en","source_url":"https://github.com/python/typeshed","tags":["excel","xls","types","stubs","typing","typeshed"],"install":[{"cmd":"pip install types-xlrd xlrd","lang":"bash","label":"Install stubs and library"}],"dependencies":[{"reason":"These are typing stubs for the `xlrd` library; `xlrd` must be installed for runtime functionality.","package":"xlrd"}],"imports":[{"symbol":"open_workbook","correct":"import xlrd; xlrd.open_workbook"},{"symbol":"Book","correct":"from xlrd.book import Book"},{"symbol":"Sheet","correct":"from xlrd.sheet import Sheet"},{"symbol":"XLRDError","correct":"from xlrd.biffh import XLRDError"}],"quickstart":{"code":"import xlrd\nimport os\n\n# Create a dummy .xls file for demonstration if it doesn't exist\n# In a real scenario, you would open an existing .xls file\nxls_file_path = 'example.xls'\nif not os.path.exists(xls_file_path):\n    # This part requires an actual .xls file or a library to create one (e.g., xlwt)\n    # For a runnable example without xlwt, we'll simulate opening.\n    # In practice, ensure 'example.xls' is a valid Excel 97-2003 file.\n    print(f\"Please create a dummy Excel 97-2003 (.xls) file named '{xls_file_path}' with some data.\")\n    print(\"For example, put 'Hello' in A1 and 'World' in B1 of Sheet1.\")\n    # For this quickstart, we'll proceed assuming the file exists\n    # and will raise an error if not, which is expected for `xlrd`.\n\ntry:\n    # Open the workbook (assumes example.xls exists and is an .xls file)\n    book: xlrd.Book = xlrd.open_workbook(xls_file_path)\n\n    # Get the first sheet by index\n    sheet: xlrd.sheet.Sheet = book.sheet_by_index(0)\n\n    # Read a cell value (e.g., A1, which is (0, 0))\n    cell_value: str = sheet.cell_value(0, 0)\n    print(f\"Value from cell A1: {cell_value}\")\n\n    # Iterate through rows and print values\n    print(\"\\nAll values in the first sheet:\")\n    for row_idx in range(sheet.nrows):\n        for col_idx in range(sheet.ncols):\n            cell = sheet.cell(row_idx, col_idx)\n            print(f\"({row_idx}, {col_idx}): {cell.value}\", end=\"\\t\")\n        print()\n\nexcept xlrd.biffh.XLRDError as e:\n    print(f\"Error opening Excel file: {e}\")\n    print(\"Make sure 'example.xls' is a valid Excel 97-2003 (.xls) file.\")\nexcept FileNotFoundError:\n    print(f\"Error: The file '{xls_file_path}' was not found. Please create it.\")\n","lang":"python","description":"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."},"warnings":[{"fix":"For `.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`.","message":"Since `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.","severity":"breaking","affected_versions":"xlrd >= 2.0.0"},{"fix":"Be 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).","message":"`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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure your project's Python interpreter is version 3.10 or newer if you intend to use `types-xlrd` for type checking.","message":"The `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.","severity":"gotcha","affected_versions":"types-xlrd >= 2.0.0.x"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}