How to Resolve Python Error "ModuleNotFoundError: No module named 'PIL'"

When working with image processing in Python, you'll almost certainly use the Pillow library, the actively maintained fork of the original Python Imaging Library (PIL).

A common point of confusion leads to the ModuleNotFoundError: No module named 'PIL'.

This error arises because while you import PIL (or specific modules like from PIL import Image) in your code, the package you need to install is actually named Pillow.

This guide explains this naming convention and provides comprehensive steps to install Pillow correctly and resolve the import error.

Understanding the Error: PIL vs. Pillow

• PIL (Python Imaging Library): The original image processing library for Python. It is largely unmaintained and does not support modern Python versions well.
• Pillow: An actively developed and maintained fork of PIL. It's designed as a drop-in replacement for PIL, offering the same functionality plus many improvements and compatibility with current Python versions.
• The Confusion: To maintain backward compatibility, Pillow keeps the original import namespace. This means you install Pillow but import PIL in your code.

The ModuleNotFoundError: No module named 'PIL' occurs because Python cannot find the PIL namespace, which is provided only when the Pillow package is correctly installed in the active environment.

Common Causes

• Pillow Not Installed: The Pillow package was never installed.
• Old PIL Installed: An outdated, incompatible version of the original PIL might be installed, potentially conflicting with Pillow.
• Incorrect Environment: Pillow was installed in a different Python environment (e.g., global) than the one running the script (e.g., a virtual environment).
• Virtual Environment Not Activated: Forgetting to activate the virtual environment before installing or running.
• IDE Misconfiguration: VS Code, PyCharm, etc., are pointing to the wrong Python interpreter.
• Filename Shadowing: Having a local file named PIL.py or pil.py.

Solution 1: Install the Pillow Package (pip/conda)

This is the primary solution. Ensure you are in the correct environment (activate your virtual environment if using one).

Uninstall Old PIL (Important Prerequisite)

Crucially, Pillow and the original PIL cannot coexist reliably. Before installing Pillow, explicitly uninstall any old PIL versions:

pip uninstall PIL
pip uninstall Pillow # Also uninstall Pillow if retrying installation
# Use pip3, python -m pip etc. as needed for your environment

note

You might get a "not installed" message, which is fine.

Install Pillow

Now, install the correct package:

• Using pip:

  pip install Pillow
  
  # Or more explicitly
  python -m pip install Pillow
  pip3 install Pillow
  python3 -m pip install Pillow
  py -m pip install Pillow # Windows
  
  # If permission issues occur (less likely in venv)
  pip install Pillow --user
  # sudo pip3 install Pillow # Avoid if possible

• Using conda (Anaconda):

  # Anaconda channel often has it, or use conda-forge
  conda install -c anaconda pillow
  # or sometimes just: conda install pillow

After installation, your import PIL or from PIL import Image statements should work.

Solution 2: Verify the Python Environment

Ensure consistency between installation and execution environments.

• Checking Python Version: Use python --version / pip --version. Pillow supports a wide range of modern Python 3 versions.

• Using Virtual Environments (Recommended):

  • Create: python3 -m venv venv
  • Activate: source venv/bin/activate (Linux/macOS) or venv\Scripts\activate (Windows)
  • Uninstall old PIL (while active): pip uninstall PIL
  • Install Pillow (while active): pip install Pillow
  • Run script (while active).

• Checking IDE Interpreter Settings: Configure VS Code ("Python: Select Interpreter") or PyCharm (File > Settings > Project > Python Interpreter) to use the Python interpreter from within your virtual environment.

• Note on VS Code Pylance Error (Import "PIL" could not be resolved) Similar to the runtime error, this static analysis error from Pylance means it can't find the PIL module source in the currently selected VS Code interpreter. The solutions are the same:

  1. Uninstall PIL if it exists (pip uninstall PIL in the venv terminal).
  2. Install Pillow (pip install Pillow in the venv terminal).
  3. Ensure VS Code has the correct virtual environment interpreter selected.
  4. Restart VS Code often helps Pylance recognize the change. You can use # type: ignore on the import line as a last resort, but it's strongly discouraged as it hides the underlying problem.

Solution 3: Check for Filename Shadowing (PIL.py / pil.py)

Do not name any of your project files PIL.py or pil.py. This will interfere with the real import. Rename any such files.

Debugging Steps

• Check Installation (pip show Pillow): Activate your environment. Run pip show Pillow. If found, check the Location. If not found, it needs installing. Do not use pip show PIL.
• Restart IDE / Kernel / Script: Close and reopen VS Code/PyCharm. Restart Jupyter kernels. Stop/start your script.
• Reinstall / Upgrade Package:

  pip uninstall PIL # Ensure old one is gone
  pip uninstall Pillow
  pip install Pillow
  # Or upgrade
  pip install --upgrade Pillow

Platform/Tool Specific Installation Guides

These sections guide opening terminals/using tools to run the essential commands: pip uninstall PIL followed by pip install Pillow or the conda equivalent.

• Install Pillow on Windows: Open Command Prompt/PowerShell (maybe as Admin). Run pip uninstall PIL, then pip install Pillow (using specific pip/python -m pip/py -m pip as needed). Use venv.
• Install Pillow on macOS or Linux: Open Terminal. Run pip uninstall PIL, then pip3 install Pillow (or specific python3 -m pip). Use venv. Consider --user or sudo only if necessary.
• Install Pillow in Visual Studio Code: Use integrated terminal (ensure correct venv). Run pip uninstall PIL, then pip install Pillow. Select correct interpreter.
• Install Pillow in PyCharm: Use terminal panel (check venv) or UI package installer (Settings > Interpreter > +). Run pip uninstall PIL, then pip install Pillow in terminal, OR search/install Pillow via UI. Set correct project interpreter.
• Install Pillow in Anaconda: Activate conda env. Use conda install -c anaconda pillow (conda uses pillow name). Or, within the conda env, use pip uninstall PIL then pip install Pillow.
• Install Pillow in Jupyter Notebook: Best: Install in terminal (activated env) before starting Jupyter. Alt: In cell, run !pip uninstall PIL -y && !pip install Pillow. Restart Kernel afterwards.

Conclusion

The ModuleNotFoundError: No module named 'PIL' arises from the historical split between the original PIL library and its modern, maintained fork, Pillow.

To fix this:

1. Uninstall any old PIL package: pip uninstall PIL.
2. Install the correct package: pip install Pillow (or conda install pillow).
3. Ensure installation occurs within the correct, active Python environment (use virtual environments).
4. Configure your IDE to use that same environment's interpreter.
5. Use import PIL or from PIL import ... in your Python code.

Following these steps correctly aligns the installed package (Pillow) with the imported namespace (PIL), resolving the error.