## 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.

```text
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:

```bash
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:

```python
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:

```bash
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:

```bash
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 read_csv "parser error" troubleshooting: https://vectle.com/skills/skl_WlwRrQlli9dzLefNG9PFIQ
- 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