How to Resolve "ModuleNotFoundError: No module named 'openpyxl'" in Python

Fix the Python error when importing openpyxl by correctly installing the library in your active environment, troubleshooting virtual environments, and resolving common pip issues.

The ModuleNotFoundError: No module named 'openpyxl' is a common error in Python that arises when you try to import openpyxl, but the library hasn't been installed in the Python environment your script is currently using. openpyxl is a popular library for reading and writing Excel (xlsx/xlsm/xltx/xltm) files.

This guide provides step-by-step solutions to install openpyxl correctly and resolve the error.

Understanding the Error

This error means Python searched its known locations for installed modules but couldn't find the openpyxl package when your code executed import openpyxl or from openpyxl import ....

Solution 1: Install `openpyxl` using `pip` (Most Common)

openpyxl is a third-party library and needs to be installed using pip, Python's package installer.

Open your terminal or command prompt and run:

pip install openpyxl

Variations (Choose the one appropriate for your setup):

pip3 install openpyxl

python -m pip install openpyxl
python3 -m pip install openpyxl

py -m pip install openpyxl

Troubleshooting Common Installation Problems:

If pip install openpyxl fails or the ModuleNotFoundError persists, check these points:

Using the Correct pip: If you have multiple Python versions, ensure you're using the pip corresponding to the Python version running your script (usually pip3 or python3 -m pip). Verify with python --version and pip --version (or pip3 --version).
Working with Virtual Environments (Crucial!): This is the most frequent cause of the error. You likely installed openpyxl globally but are running your script inside a virtual environment (or vice-versa).
- Activate your virtual environment before installing:
```
python3 -m venv venv
source venv/bin/activate       # Linux/macOS
.\venv\Scripts\Activate.ps1   # Windows PowerShell
.\venv\Scripts\activate.bat    # Windows CMD
pip install openpyxl
```
- Confirm your IDE (VS Code, PyCharm) uses the Python interpreter from the activated virtual environment.
Permissions Issues (--user or sudo): When installing globally (outside a venv).
- Recommended: Install for the current user: pip install openpyxl --user
- Use Cautiously: Use admin/root privileges: sudo pip install openpyxl (Linux/macOS) or Run Terminal as Administrator (Windows). Virtual environments avoid this.
Multiple Python Installations / IDE Configuration: Double-check that the Python interpreter selected in your IDE matches the one you used pip with. Use the "Select Interpreter" command in your IDE.
Naming Conflicts (openpyxl.py): Ensure none of your project files are named openpyxl.py. This "shadows" the installed package. Rename your file if necessary. Also, avoid using openpyxl as a variable name before the import.

Verifying Installation (`pip show`)

Confirm openpyxl is installed in the active environment:

pip show openpyxl

This command should display package details (Name, Version, Location, etc.). "Package(s) not found" means it's not installed in that environment.

Platform/Tool Specific Installation Notes:

Windows: Use CMD or PowerShell. py -m pip install openpyxl is reliable. Use "Run as administrator" for global installs if needed (prefer venvs/--user).
macOS / Linux: Use the Terminal. Use pip3 or python3 -m pip. Use sudo cautiously for global installs.
VS Code: Use the integrated terminal (Ctrl + `` ). Ensure the correct interpreter (often venv) is active.
PyCharm: Use the Terminal (Alt+F12) or Python Packages tool (File > Settings > Project > Python Interpreter > +). Ensure the correct project interpreter.
Anaconda: Use Anaconda Prompt/Navigator or terminal in an active conda environment. Preferred command:
```
conda install -c anaconda openpyxl
```
Jupyter Notebook: Install from a notebook cell:
```
!pip install openpyxl
```
Restart the kernel after installation.

Using `openpyxl` After Installation

Once installed, you can import and use the library:

import datetime
from openpyxl import Workbook # Or load_workbook, etc.

try:
    wb = Workbook()
    ws = wb.active
    ws['A1'] = 42
    ws.append([1, 2, 3])
    ws['A2'] = datetime.datetime.now()
    wb.save("sample.xlsx")
    print("Excel file 'sample.xlsx' created successfully.")

except ImportError:
    print("Error: 'openpyxl' module not found. Please install it using 'pip install openpyxl'.")
except Exception as e:
    print(f"An error occurred: {e}")

Conclusion

The ModuleNotFoundError: No module named 'openpyxl' indicates that the openpyxl library is missing from your active Python environment.

The solution is to install it using pip install openpyxl.
Always ensure you are installing into the correct environment, preferably using a virtual environment, and verify that your IDE is configured accordingly.
Double-check for naming conflicts with your own files.