pandas read_excel: Missing optional dependency 'openpyxl' (tested)

ImportError: Missing optional dependency 'openpyxl' from pd.read_excel means the Excel reader package is not installed in the Python running pandas. On pandas 3.1.0 the message reads `Import openpyxl` failed, and .xls files need python-calamine instead of xlrd. Tested on both versions.

1. The error on pandas 2 and pandas 3

import pandas as pd

for path in ("report.xlsx", "old.xls"):
    try:
        pd.read_excel(path)
    except ImportError as e:
        print(path, "->", type(e).__name__ + ":", e)

Output with pandas 2.3.3:

report.xlsx -> ImportError: Missing optional dependency 'openpyxl'.  Use pip or conda to install openpyxl.
old.xls -> ImportError: Missing optional dependency 'xlrd'. Install xlrd >= 2.0.1 for xls Excel support Use pip or conda to install xlrd.

Output with pandas 3.1.0:

report.xlsx -> ImportError: `Import openpyxl` failed.  Use pip, conda, or your preferred package management tool to install the openpyxl package.
old.xls -> ImportError: `Import python-calamine` failed.  Use pip, conda, or your preferred package management tool to install the python-calamine package.

pandas does not ship an Excel reader: .xlsx files need the optional openpyxl package. For old .xls files pandas 2 asks for xlrd, while pandas 3.1.0 asks for python-calamine. The pandas 3 message is also worded differently ("`Import openpyxl` failed"), so search results for the old text may not match.

2. Fix: install the reader into the same Python

python -m pip install openpyxl          # .xlsx (pandas 2 and 3)
python -m pip install python-calamine   # .xls on pandas 3
python -m pip install xlrd             # .xls on pandas 2

After installing openpyxl 3.1.5 a write-and-read round trip worked on both versions ([[1]]). Use python -m pip (or %pip install in Jupyter) so the package goes into the interpreter that runs pandas; a bare pip often belongs to another Python (see No module named requests for the same issue). On pandas 3.1.0 with only xlrd installed, reading an .xls still uses xlrd but warns: Pandas4Warning: The xlrd engine is deprecated and will be removed in a future version. Use the calamine engine instead, by setting engine='calamine'.

Related: read_csv Error tokenizing data · KeyError but the column exists · to_datetime errors='ignore' deprecated.

Written with AI assistance. Measured on 2026-10-23 in the python:3-alpine Docker image (Python 3.14) with pandas 2.3.3 and pandas 3.1.0, before and after installing openpyxl 3.1.5 and xlrd 2.0.2. Outputs pasted unedited. PlainHeaders is our extension; Python, pandas and the Excel readers are free.