Pandas ImportError About openpyxl Reading Excel Files? Fix It

You run a simple pandas command to open an Excel file. Instead of seeing your data, Python stops with an ImportError that mentions openpyxl. This error confuses many beginners because the file itself is usually fine. The real problem is a missing library that pandas needs in the background.

Pandas is great at working with tables, but it does not read Excel files on its own. It relies on another package to do that job. When that package is missing, outdated, or installed in the wrong place, you get this ImportError. The good news is that this is one of the easiest Python errors to fix once you understand why it happens.

Quick Answer

Pandas throws an ImportError about openpyxl when reading an Excel file because pandas needs the openpyxl library to open .xlsx files, and that library is not installed in your current Python environment. Install it with pip install openpyxl using the same Python you run your script with. Then restart your editor or kernel and run the code again.

What the Error Actually Means

When you write pd.read_excel("data.xlsx"), pandas looks at the file extension. For modern Excel files with the .xlsx extension, pandas chooses openpyxl as the engine. An engine is simply the helper library that does the actual reading.

If openpyxl is not found, pandas cannot continue. It raises an ImportError with a message similar to this:

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

The words “optional dependency” are important. Pandas does not install every possible file reader when you install pandas itself. Some readers are optional because not everyone needs them. If you only work with CSV files, you may never need openpyxl at all. The moment you try to read an Excel file, that optional tool becomes required.

Why openpyxl Is Missing in Your Environment

There are several common reasons why this happens, even for people who are sure they already installed it.

You installed it in a different environment

This is the most common cause. You might have run pip install openpyxl in one terminal, but your script runs in a virtual environment, a conda environment, or Jupyter with a different kernel. Each environment has its own separate set of packages. Installing a package in one place does not make it available everywhere.

You have more than one Python installed

Many computers have two or three Python versions at the same time. Your system might use Python 3.9 for one tool and Python 3.11 for another. If pip belongs to one version and your script runs on another, the install will seem to succeed but the script still cannot find the package.

The package was never part of your project setup

If you copied a project from a colleague or downloaded it from the internet, the requirements file may not list openpyxl. Pandas was installed, but this extra dependency was left out. Your code then fails only when it reaches the Excel reading step, which makes the problem look random.

How to Fix the ImportError Step by Step

Follow these steps in order. Most people fix the problem at step one or step two.

1. Open the same terminal or environment where you run your Python code.
2. Check which Python you are using by running python --version and pip --version. Both should point to the same version and location.
3. Install openpyxl with the safest command: python -m pip install openpyxl. Using python -m pip ensures the package goes into the exact Python that runs your script.
4. Wait for the success message. You should see a line confirming that openpyxl and its dependency et-xmlfile were installed.
5. Restart your editor, terminal, or Jupyter kernel completely. Old sessions sometimes keep a cached view of installed packages.
6. Run your pandas code again with pd.read_excel("your_file.xlsx").

If you use Anaconda or Miniconda, you can use conda instead:

conda install openpyxl

Do not mix pip and conda randomly inside the same environment if you can avoid it. Pick the tool you normally use for that environment and stick with it. Mixing them can create version conflicts that are hard to trace later.

How to Check If openpyxl Is Installed Correctly

Before blaming your code, run a quick test. In Python, type the following:

import openpyxl

print(openpyxl.__version__)

If both lines run without an error and print a version number such as 3.1.2, openpyxl is installed and working in that environment. If the first line still fails, the package is still not in the right place, no matter what pip reported earlier.

You can also list all installed packages with python -m pip list and look for openpyxl in the output. This is a useful habit whenever an import fails. If you are troubleshooting other missing modules, our detailed walkthrough on fixing Python ModuleNotFoundError errors step by step covers the same environment checks in more depth.

Specifying the Engine Manually

Pandas allows you to tell it exactly which engine to use. This does not fix a missing package, but it makes the error message clearer and confirms what pandas is trying to do.

df = pd.read_excel("data.xlsx", engine="openpyxl")

For older Excel files with the .xls extension, pandas uses a different engine called xlrd. Newer versions of xlrd no longer support .xlsx files, so use openpyxl for .xlsx and xlrd only for old .xls files. Confusing the two is another frequent source of errors.

You can read the full list of supported engines and options in the official pandas read_excel documentation, which explains each parameter with examples. For package details, version history, and installation notes, the openpyxl project page on PyPI is the authoritative source.

Fixing the Error in Jupyter Notebook

Jupyter causes extra confusion because the notebook kernel and the terminal often point to different environments. Installing openpyxl in your system terminal does not always help the notebook.

To fix it inside Jupyter, run this command in a notebook cell:

%pip install openpyxl

The magic command with the percent sign installs the package into the exact environment that the current kernel uses. After the install finishes, restart the kernel from the Kernel menu and run your cells again from the top. Skipping the kernel restart is the reason many people think the install did not work.

Fixing the Error in VS Code

In VS Code, the problem is usually the selected interpreter. VS Code might be running your script with a Python that has no openpyxl, while your terminal uses a different one that does.

• Open the Command Palette and choose Python: Select Interpreter.
• Pick the environment where you installed openpyxl.
• Open a new terminal inside VS Code so it activates that environment.
• Run python -m pip install openpyxl once more in that terminal to be safe.
• Run your script again.

Common Mistakes and Useful Tips

Even after learning the main fix, people repeat a few small mistakes. Avoiding them will save you time on every future project.

• Installing with plain pip only: On systems with multiple Pythons, plain pip may belong to a different version. Always prefer python -m pip install openpyxl.
• Forgetting to restart: Editors, notebooks, and long running terminals need a restart to notice a new package. Close and reopen them after installing.
• Naming your file openpyxl.py: If your own script is named openpyxl.py or pandas.py, Python will import your file instead of the real library and produce strange errors. Rename your file to something else.
• Ignoring virtual environments: Create one environment per project and install all needed packages there. This prevents most import problems before they start.
• Not saving the dependency: After a successful install, add openpyxl to your requirements file with pip freeze > requirements.txt so the next person does not face the same error.
• Using an outdated pandas: Very old pandas versions handle Excel engines differently. Keep pandas reasonably up to date with python -m pip install --upgrade pandas openpyxl.

Conclusion

The pandas ImportError about openpyxl does not mean your Excel file is broken or your code is wrong. It simply means pandas cannot find the helper library it needs to read .xlsx files in your current environment. Install openpyxl with python -m pip install openpyxl in the exact environment that runs your code, restart your editor or kernel, and test the import on its own. Once you build the habit of checking environments and interpreters first, this class of error becomes quick and predictable to solve every time.

Frequently Asked Questions

Do I need openpyxl if I only read CSV files?

No. Pandas reads CSV files with its built in tools and does not need openpyxl for them. You only need openpyxl when you read or write Excel files with the .xlsx extension. If your work never touches Excel, you can safely leave it uninstalled.

Why does pip say openpyxl is already installed but pandas still fails?

This almost always means pip and your script use different Python environments. Run python -m pip install openpyxl from the same terminal or kernel that runs your script, then restart the session. Also check that you did not name your own file openpyxl.py, which would shadow the real library.

Can I use a different library instead of openpyxl?

Yes. For reading .xlsx files you can also use xlsxwriter only for writing, or pyxlsb for binary Excel files, depending on the format. For standard .xlsx reading, openpyxl remains the default and best supported choice in pandas, so installing it is usually simpler than switching engines.

How do I fix this error on a shared or work computer without admin rights?

You can install the package only for your user account with python -m pip install --user openpyxl. Better still, create a virtual environment inside your project folder and install everything there. Neither option needs administrator permission on most systems.

Does reinstalling pandas automatically install openpyxl?

No. Reinstalling pandas alone does not add its optional dependencies. You must install openpyxl separately, or install pandas with its Excel extras where supported. That is why the error specifically tells you to install openpyxl by name.