Fix No Module Named PIL: Install Pillow Correctly

ModuleNotFoundError: No module named PIL means the Python interpreter running your code cannot import Pillow’s PIL namespace. The package is installed as Pillow, but the import name remains PIL.

Quick Answer

Check the active interpreter, install Pillow with that interpreter’s -m pip, restart the IDE or notebook kernel, and verify with from PIL import Image. Do not install a package named PIL.

The primary references are Pillow’s basic installation guide, PIL-to-Pillow porting notes, and Image module reference. Pillow documents the important distinction: install the Pillow distribution and import from the PIL namespace.

Check The Python That Runs Your Code

Start inside the failing script, notebook, or interactive console. The executable path is more reliable than the name of a terminal command.

import sys

print(sys.executable)
print(sys.version)

Compare this path with the interpreter selected by your IDE or notebook kernel. A global Python, a virtual environment, Conda, and a deployment service can all have separate site-packages directories.

Install Pillow Into That Interpreter

Use python -m pip so the package installer is tied to a specific Python executable.

import sys
import subprocess

subprocess.check_call([sys.executable, '-m', 'pip', 'install', 'Pillow'])

For a terminal, the equivalent command is python -m pip install --upgrade Pillow. If the diagnostic printed a full path, run that path with -m pip. This avoids the common mistake of running a pip command that belongs to another Python.

Use The Correct Import Name

Pillow is the maintained distribution, but it preserves the PIL import namespace for compatibility with the Python Imaging Library.

from PIL import Image
import PIL

print(PIL.__version__)
print(Image.__name__)

Do not change the import to from Pillow import Image; that is not the normal Pillow API. Do not use pip install PIL as the fix for a modern Python 3 project.

Test A Minimal Image Operation

A small in-memory image separates an import problem from a file path, permissions, or unsupported-format problem.

from PIL import Image

image = Image.new('RGB', (2, 2), color='white')
print(image.mode)
print(image.size)

If this test works but Image.open() fails on a real file, inspect the file path, permissions, file signature, and format support separately. The module is already importable in that process.

Diagnose IDE And Notebook Mismatches

If the terminal import works but the editor still reports the error, compare the executable path in both environments. Restart the running kernel or application after installing a package; long-lived processes do not always reload site-packages automatically.

For notebooks, run the executable check in the failing kernel rather than in a separate terminal. For services and containers, add Pillow to the project’s dependency file and rebuild the environment rather than relying on a manual one-off install.

Inspect The Import Search Path

When the environment still looks correct, inspect how Python resolves the module.

import importlib.util

spec = importlib.util.find_spec('PIL')
print(spec.origin if spec else 'PIL is not importable')

A result from another directory or interpreter does not prove that the failing process can import the package. Keep the executable, package version, and environment configuration together when reporting the problem.

Common PIL Import Mistakes

• Installing Pillow with one Python and running code with another.
• Trying to install PIL instead of Pillow.
• Using a notebook kernel that is not the environment shown by the terminal.
• Changing the import to a nonexistent Pillow namespace.
• Assuming a later image-file error means the module is still missing.

The reliable workflow is: identify sys.executable, install Pillow through that executable, restart the process, and verify from PIL import Image. Keep the dependency in project configuration so deployment and teammates use the same setup.

Virtual Environments

Activate the project’s virtual environment before running a short command such as python -m pip install Pillow, or use the full executable path printed by the diagnostic. The important point is not the activation command itself; it is that the package and the script use the same interpreter.

After installation, check the package from the same shell and from the application entry point. A web server, scheduled job, notebook kernel, and terminal may each have a different environment even when they live in the same project directory.

Conda, IDEs, And Containers

Conda environments, IDE interpreter selectors, and containers each control their own package paths. Select the intended environment first, then install Pillow through its Python. In a container, put Pillow in the dependency file or image build rather than installing it manually into a running container.

On deployment, record the Python version and Pillow version. Reproducible dependency installation is more reliable than assuming the production host has the same global packages as a development machine.

When The Import Works But An Image Fails

A successful from PIL import Image test proves that the module is available, not that every image file is valid. A later error may mean the path is wrong, the file is truncated, the format is unsupported, or the process lacks permission to read it.

Use an absolute path temporarily, print the file’s existence and size, and test a known-good small image. Keep module installation diagnosis separate from file-content diagnosis so the fix remains targeted.

Keep Pillow In Project Dependencies

Add Pillow to the project’s requirements or dependency configuration after the local import works. Pin a compatible range when reproducibility matters, and update it deliberately with tests for the image formats the application actually uses.

For a support report, include the exact import, sys.executable, Python version, Pillow version, operating system, and whether the code runs in an IDE, notebook, service, or terminal. Those details usually expose an environment mismatch quickly.

For the next image-processing step, compare converting a PIL image to NumPy and fixing image-array dtype errors. Read pil image to numpy array and fixed image data of dtype object cannot be converted to float for the related workflow.

Frequently Asked Questions

Why does Python say No module named PIL?

The interpreter running the code cannot find Pillow’s PIL import namespace. The most common cause is that Pillow is missing from that interpreter or was installed into a different environment.

Do I install PIL or Pillow?

Install the maintained Pillow distribution with python -m pip install Pillow. The code import remains from PIL import Image.

Why does pip install Pillow but the import still fail?

The pip command may belong to a different Python installation than the script, IDE, notebook kernel, or service. Compare sys.executable and install with that exact interpreter.

How do I test that Pillow works?

Run from PIL import Image, print the Pillow version, and create a tiny in-memory image. If that succeeds, a later file or path error is separate from the missing-module problem.