ImportError: Missing optional dependency 'xlrd'. Use pip or conda to install xlr

Not specified by the original author.

TL;DR: pandas needs the xlrd package to read legacy .xls files and it is not installed. Run pip install xlrd and re-run your read_excel call. For modern .xlsx files install openpyxl instead.

The error

ImportError: Missing optional dependency 'xlrd'. Use pip or conda to install xlrd.

Fix it

1. Install the Excel engine your file format needs:

   pip install xlrd

   Expected: install completes.

2. Re-run the read:

   import pandas as pd
   df = pd.read_excel("your_file.xls")
   print(df.head())

   Expected: prints the first rows instead of raising.

3. If your file is .xlsx (not .xls), install openpyxl instead:

   pip install openpyxl

When this applies

Use this when pd.read_excel raises the missing-xlrd message, which means the file is the legacy BIFF (.xls) format.

When it does not apply

If the error names openpyxl, pyxlsb, or odf, install that engine instead. If the file will not open even with the engine installed, the file itself may be corrupt.

Compatibility

All pandas versions. xlrd 2.x only reads .xls; it dropped .xlsx support, which is why .xlsx files need openpyxl.

Root cause

pandas keeps Excel engines as optional dependencies to stay light. It picks the engine from the file extension, and .xls maps to xlrd, which is not installed by default.

Edge cases

xlrd>=2.0 refuses .xlsx files with a clear error; do not fight it, use openpyxl. In locked-down environments, add xlrd to requirements so deploys do not regress.

A commit in aws-solutions-library-samples/accelerated-intelligent-document-processing-on-aws fixed exactly this: their pipeline advertised .xls support but never declared xlrd, so pd.read_excel raised Missing optional dependency 'xlrd' and the workbook came back empty. The verified fix was declaring xlrd as a dependency (xlrd==2.0.2 in their case) and installing it, after which reading the .xls fixture returned real cell content. Commit: https://github.com/aws-solutions-library-samples/accelerated-intelligent-document-processing-on-aws/commit/ce2e941cd14b954d7e2fcbbd776ef81a38703b88

Not specified by the original author.

How to fix ImportError: Missing optional dependency 'openpyxl'. Use pip or conda to install openpyxl.

Install the Excel engine: python -m pip install openpyxl. pandas deliberately does not bundle Excel readers; read_excel on an .xlsx file needs openpyxl installed in the same environment. Use the exact same python/pip pair (python -m pip) so it lands in the right env.

The exact error

ImportError: Missing optional dependency 'openpyxl'. Use pip or conda to install openpyxl.

Fix it

1. Run python -m pip install openpyxl. Expected: pip reports Successfully installed openpyxl

2. Retry pd.read_excel('file.xlsx'). Expected: returns a DataFrame, no ImportError

3. For legacy .xls files you need xlrd instead: python -m pip install xlrd. Expected: read_excel works on .xls

When this applies

pd.readexcel / ExcelFile / toexcel on .xlsx raises Missing optional dependency 'openpyxl'

When this does NOT apply

the file itself is missing (FileNotFoundError) or corrupt (BadZipFile)

Versions

pandas >= 1.0 reading .xlsx

Why it happens

Excel IO engines are optional dependencies; pandas raises a helpful ImportError telling you which one to install.

Edge cases

xlrd >= 2.0 dropped .xlsx support, so do not 'fix' this by installing xlrd for an .xlsx file.

Asked about: ImportError: Missing optional dependency 'openpyxl'. Use pip or conda to install openpyxl. (web:pythonfriday readexcel guide). The verified fix: Install the Excel engine: python -m pip install openpyxl. pandas deliberately does not bundle Excel readers; `readexcel on an .xlsx file needs openpyxl installed in the same environment. Use the exact same python/pip pair (python -m pip`) so it lands in the right env. Full thread: https://pythonfriday.dev/2025/04/274-working-with-excel-files-in-pandas/

Not specified by the original author.

Short answer: pandas needs the optional openpyxl package to read and write .xlsx files. Install it in the same environment, then rerun. `` ImportError: Missing optional dependency 'openpyxl'. Use pip or conda to install openpyxl. 1. Run python -m pip install openpyxl (conda users: conda install openpyxl). In a Jupyter notebook use !pip install openpyxl and then restart the kernel. Expected: install completes cleanly. 2. Verify with python -c "import openpyxl; print(openpyxl.version)". Expected: a version number prints. 3. Rerun pd.readexcel("file.xlsx"). Expected: a DataFrame, no ImportError. 4. If the error persists, you installed into a different interpreter. Check python -c "import sys; print(sys.executable)" and reinstall using that Python's -m pip. Root cause: pandas treats Excel engines as optional to keep the base install small. The error message names the missing engine, so there is nothing to diagnose beyond installing it. When to use: reading or writing .xlsx files with pandas. When NOT to use: legacy .xls files need xlrd, and .ods files need odfpy`, openpyxl will not help there. Variant phrasings: "importerror missing optional dependency openpyxl", "pandas readexcel openpyxl", "use pip or conda to install openpyxl". Edge cases: on managed platforms that block pip installs (some notebook hosts, workflow tools) you cannot install it yourself, check the platform's package policy instead.

Context: pandas deliberately keeps Excel support out of its base install and loads it as an optional dependency. When you call pd.read_excel on an .xlsx file without openpyxl installed, pandas raises this ImportError and tells you exactly what to install. The fix is one install command in the right environment.

Source: pandas deliberately keeps Excel support out of its base install and loads it as an optional dependency. When you call pd.read_excel on an .xlsx file without openpyxl installed, pandas raises this ImportError and tells you exactly what to install. The fix is one install command in the right environment.

Verified resolution: Short answer: pandas needs the optional openpyxl package to read and write .xlsx files. Install it in the same environment, then rerun. `` ImportError: Missing optional dependency 'openpyxl'. Use pip or conda to install openpyxl. 1. Run python -m pip install openpyxl (conda users: conda install openpyxl). In a Jupyter notebook use !pip install openpyxl and then restart the kernel. Expected: install completes cleanly. 2. Verify with python -c "import openpyxl; print(openpyxl.version)". Expected: a version number prints. 3. Rerun pd.readexcel("file.xlsx"). Expected: a DataFrame, no ImportError. 4. If the error persists, you installed into a different interpreter. Check python -c "import sys; print(sys.executable)" and reinstall using that Python's -m pip. Root cause: pandas treats Excel engines as optional to keep the base install small. The error message names the missing engine, so there is nothing to diagnose beyond installing it. When to use: reading or writing .xlsx files with pandas. When NOT to use: legacy .xls files need xlrd, and .ods files need odfpy`, openpyxl will not help there. Variant phrasings: "importerror missing optional dependency openpyxl", "pandas readexcel openpyxl", "use pip or conda to install openpyxl". Edge cases: on managed platforms that block pip installs (some notebook hosts, workflow tools) you cannot install it yourself, check the platform's package policy instead.

Source URL: https://pandas.pydata.org/docs/getting_started/install.html