Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

pandas still says Missing optional dependency openpyxl after pip install

ErrorImportError: Missing optional dependency 'openpyxl'

Short answer

pandas imports openpyxl at the moment you read or write an xlsx file. If it still fails after pip install, the package went to a different Python than the one running your script, or it is older than the version pandas needs. Install with that interpreter's own python -m pip.

  • Applies to pandas 2, Python 3.12, openpyxl 3.1.5
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Ask the interpreter that runs your script where it lives and whether it can import the package.

    python -c "import sys; print(sys.executable)"
    python -c "import openpyxl; print(openpyxl.__version__, openpyxl.__file__)"
  2. 2Match what you see, then jump to its fix

    1. 1The second command fails or shows another path, while pip reports the package as installedpip installed into a different Python than the one running the scriptFix
    2. 2sys.executable points outside your project's venv folderThe virtual environment is not active, or the editor uses another oneFix
    3. 3The import works, but pandas still reports the dependency as missing or too oldThe installed openpyxl is older than pandas supportsFix

What does the error look like?

  • ImportError: Missing optional dependency 'openpyxl'
  • pip install openpyxl says Requirement already satisfied, but the error stays

Cause 1 of 3

pip installed into a different Python than the one running the script

1Check

pip and python on PATH can belong to different installations. Python's docs say a virtual environment keeps its own site-packages, isolated from the base installation.

which python pip
python -m pip --version

2Fix

Install with the same interpreter that runs the script, using python -m pip.

python -m pip install openpyxl

3Verify

The import works from the same interpreter.

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

Confirmed by pip.pypa.io

Did this fix it?

Cause 2 of 3

The virtual environment is not active, or the editor uses another one

1Check

Activation puts the venv's bin folder first on PATH. You can also skip activation and run the venv's interpreter by its full path.

python -c "import sys; print(sys.prefix != sys.base_prefix)"

2Fix

Activate the environment, or call its interpreter directly, then install there. In an editor, select that interpreter.

source .venv/bin/activate
python -m pip install openpyxl
# or without activating
.venv/bin/python -m pip install openpyxl

3Verify

sys.prefix differs from sys.base_prefix and the import works.

python -c "import sys; print(sys.prefix != sys.base_prefix)"
python -c "import openpyxl"

Confirmed by docs.python.org

Did this fix it?

Cause 3 of 3

The installed openpyxl is older than pandas supports

1Check

pandas lists 3.1.5 as the minimum openpyxl version for reading and writing xlsx files. Compare it with what you have.

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

2Fix

Upgrade openpyxl, or install pandas with its Excel extra so the matching versions come together.

python -m pip install --upgrade openpyxl
# or
python -m pip install "pandas[excel]"

3Verify

read_excel opens an xlsx file.

python -c "import pandas as pd; print(pd.read_excel('data.xlsx').head())"

Confirmed by pandas.pydata.org

Did this fix it?

How do I stop it coming back?

  • Always install with python -m pip so the package and the script share one interpreter.
  • Create one venv per project and list pandas[excel] in the requirements file.
  • Print sys.executable when an import fails; it settles which Python runs.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.