Install & Compatibility
Where this runs
tested against v12.3.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.070s · 37.4MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.3s · import 0.066s · 38MB
35MB installed
● package 35MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Image
✓ from PIL import Image
✗ import Image
Direct import of Image without PIL prefix is incorrect.
ImageDraw
✓ from PIL import ImageDraw
✗ import ImageDraw
Direct import of ImageDraw without PIL prefix is incorrect.
ImageFont
✓ from PIL import ImageFont
✗ import ImageFont
Direct import of ImageFont without PIL prefix is incorrect.
Open an image file, display it, and save it in a different format.
from PIL import Image
# Open an image file
with Image.open('example.jpg') as img:
# Display image
img.show()
# Save image in a different format
img.save('example.png')
Debug
Known issues
breakingDropped support for Python 3.9 in version 12.0.0.fixUpgrade to Python 3.10 or later.
affects: 12.0.0 and later
breakingRemoved support for FreeType <= 2.9.0 in version 12.0.0.fixUpgrade FreeType to version 2.10.0 or later.
affects: 12.0.0 and later
deprecatedDeprecated getdata() in favor of get_flattened_data() in version 12.1.0.fixUse get_flattened_data() instead of getdata().
affects: 12.1.0 and later
deprecatedDeprecated Image._show in version 12.0.0.fixUse alternative methods for displaying images.
affects: 12.0.0 and later
gotchaUsing _getexif() may return None if the image lacks EXIF data.fixCheck if _getexif() returns None before accessing its contents.
affects: All versions
gotchaImage.open() raises FileNotFoundError if the specified image file does not exist at the given path.fixEnsure the image file exists at the specified path and has appropriate read permissions.
affects: All versions
breakingAttempting to open a non-existent image file raises `FileNotFoundError`.fixVerify the image file path and ensure the file exists before calling `Image.open()`.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'PIL'
This error occurs because the original Python Imaging Library (PIL) is outdated and has been superseded by Pillow. Developers often try to import the old 'PIL' package directly without installing Pillow, or they have Pillow installed but use an incorrect import statement.
fixFirst, ensure Pillow is installed using `pip install Pillow`. Then, import the `Image` module using `from PIL import Image`.
AttributeError: type object 'Image' has no attribute 'open'
This typically happens due to a namespace conflict, often when another library (like `tkinter` with `from tkinter import *`) also defines an 'Image' object, masking Pillow's `Image` module. It can also occur if `Image.open` is incorrectly cased as `Image.Open`.
fixTo fix this, avoid global imports like `from tkinter import *`. Instead, import specific components (e.g., `import tkinter as tk`) or explicitly import `Image` from Pillow as `from PIL import Image` and ensure correct casing (`Image.open()`).
PIL.UnidentifiedImageError: cannot identify image file
This error means Pillow cannot recognize or open the specified image file. Common causes include an incorrect file path, a corrupted image file, an unsupported image format, or the file being locked by another process.
fixVerify the image file path is correct and the file exists. Ensure the image is not corrupted and is in a supported format. If applicable, close any other applications or processes that might be holding the file open. For web sources, ensure the data stream is a valid image.
OSError: cannot open resource
This error frequently occurs when Pillow's `ImageFont.truetype()` function cannot locate the specified font file. This can be due to an incorrect font path, the font not being installed on the system, or permission issues preventing access to the font file.
fixProvide the full, absolute path to the `.ttf` or `.otf` font file. Ensure the font file exists at that location and that your program has read permissions. On some systems (like macOS), you might need to specify the exact system font directory.
SyntaxError: invalid syntax
This error typically appears when a shell command like `pip install pillow` is executed inside the Python interactive interpreter (where you see `>>>` or `In [1]:`), instead of being run directly in the system's terminal or command prompt.
fixExit the Python interpreter by typing `exit()` or pressing `Ctrl+D` (Unix/macOS) / `Ctrl+Z` then `Enter` (Windows), and then run the `pip install pillow` command in your operating system's command line interface (terminal/command prompt).
Upgrade
Version history
12.3.0latest on PyPI · released Jul 1, 2026
Audit
Dependencies
libjpegrequiredRequired for JPEG support
zlibrequiredRequired for PNG support
libtiffoptionalRequired for TIFF support
freetypeoptionalRequired for TrueType font support