importerror: `import openpyxl` failed. use pip or conda to install the openpyxl package.

TL;DR

pd.read_excel on an .xlsx file needs the openpyxl package and pandas doesnt bundle it. This ImportError is pandas telling you to install it in the same environment that runs pandas: python -m pip install openpyxl (or conda install -c conda-forge openpyxl), then the read works.

importerror: `import openpyxl` failed. use pip or conda to install the openpyxl package.

Use this when

• pd.read_excel raises this ImportError on an .xlsx file
• An agent's script reads Excel in a fresh container and fails
• Excel reads worked before a dependency cleanup removed openpyxl
• The error says "use pip or conda": it accepts either installer, use whichever owns your environment

Not for this skill when

• The file is .xls (legacy format, needs xlrd instead)
• The workbook is corrupted (thats a file problem, not a missing package)
• Writing to Excel fails (same package, but check the write path separately)

Steps

1. Install openpyxl with the same Python that runs pandas:

python -m pip install openpyxl
python -c "import openpyxl; print(openpyxl.__version__)"

Expected output: a version number prints with no ImportError. python -m pip guarantees the package lands in the environment that runs your script, not some other Python on the box.

2. Retry the read:

import pandas as pd
df = pd.read_excel("report.xlsx", sheet_name=0)
print(df.shape, df.columns.tolist()[:3])

Expected output: the shape and first columns print. If you need the engine explicitly, pass engine="openpyxl".

3. If the error persists after install, check for a venv mismatch:

which python; python -m pip show openpyxl | head -3

Expected output: pip show finds openpyxl under the python you run. Notebooks are the classic trap: the kernel and the terminal pip belong to different envs.

4. For conda environments, install from conda-forge to keep the solver happy:

conda install -c conda-forge openpyxl

Expected output: conda resolves and installs without conflicts. Mixing pip and conda installs of the same package can produce the "installed but not importable" state, so pick one installer per environment.

Variant phrasings

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

Newer pandas phrases it this way; same fix, same install command.

read_excel works locally but fails in Docker

openpyxl isnt in the image's requirements. Add it to requirements.txt and rebuild; dont pip install at container start.

pip installed openpyxl but the import still fails

Venv mismatch (step 3): the pip that installed it and the python that imports it are different interpreters.

Why it happens

pandas keeps Excel I/O behind optional dependencies to stay lean. read_excel picks an engine by file extension (openpyxl for .xlsx), and when the engine package is absent it raises this ImportError with install instructions. Agents hit it constantly because they write read_excel calls into scripts running in minimal environments where nobody installed the Excel stack.

Edge cases

• .xlsb binary workbooks need pyxlsb, not openpyxl.
• Very large .xlsx files may need read_only mode or chunking; the import fix just gets you past the first error.
• Password-protected workbooks cant be opened by openpyxl at all; decrypt first with a tool that supports it.

Related skills

• pandas readcsv "parser error" troubleshooting: https://vectle.com/skills/sklWlwRrQlli9dzLefNG9PFIQ
• Fix ipywidgets that render blank or fail in JupyterLab: https://vectle.com/skills/skl_RHL08VYbzbtIksSN0Q1kWQ
• importerror: cannot import name 'display' from 'ipython.core.display': https://vectle.com/skills/skl_QNALC7zZkKS2S3p3IlkPcg

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_CYvoPBmkNkmRoKEZPFwIEA