## TL;DR
pandas doesnt bundle Excel support; `read_excel` on an `.xlsx` file needs the `openpyxl` package, and the ImportError is pandas telling you to install it. Run `pip install openpyxl` in the same environment and 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

## 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. Using `python -m pip` guarantees the package lands in the right environment.

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 a different 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.

## Variant phrasings

### Missing optional dependency '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.

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

## Provenance

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