Deprecations and removals¶
This page lists Pillow features that are deprecated, or have been removed in past major releases, and gives the alternatives to use instead.
Deprecated features¶
Below are features which are considered deprecated. Where appropriate,
a DeprecationWarning is issued.
ImageFile.raise_oserror¶
Deprecated since version 10.2.0.
ImageFile.raise_oserror() has been deprecated and will be removed in Pillow
12.0.0 (2025-10-15). The function is undocumented and is only useful for translating
error codes returned by a codec’s decode() method, which ImageFile already does
automatically.
IptcImageFile helper functions¶
Deprecated since version 10.2.0.
The functions IptcImageFile.dump and IptcImageFile.i, and the constant
IptcImageFile.PAD have been deprecated and will be removed in Pillow
12.0.0 (2025-10-15). These are undocumented helper functions intended
for internal use, so there is no replacement. They can each be replaced
by a single line of code using builtin functions in Python.
ImageCms constants and versions() function¶
Deprecated since version 10.3.0.
A number of constants and a function in ImageCms have been deprecated.
This includes a table of flags based on LittleCMS version 1 which has been
replaced with a new class ImageCms.Flags based on LittleCMS 2 flags.
Deprecated |
Use instead |
|---|---|
|
No replacement |
|
|
|
|
|
|
|
No replacement |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
ImageMath eval()¶
Deprecated since version 10.3.0.
ImageMath.eval() has been deprecated. Use lambda_eval() or
unsafe_eval() instead.
BGR;15, BGR 16 and BGR;24¶
Deprecated since version 10.4.0.
The experimental BGR;15, BGR;16 and BGR;24 modes have been deprecated.
Non-image modes in ImageCms¶
Deprecated since version 10.4.0.
The use in ImageCms of input modes and output modes that are not Pillow
image modes has been deprecated. Defaulting to “L” or “1” if the mode cannot be mapped
is also deprecated.
Support for LibTIFF earlier than 4¶
Deprecated since version 10.4.0.
Support for LibTIFF earlier than version 4 has been deprecated. Upgrade to a newer version of LibTIFF instead.
ImageDraw.getdraw hints parameter¶
Deprecated since version 10.4.0.
The hints parameter in getdraw() has been deprecated.
FreeType 2.9.0¶
Deprecated since version 11.0.0.
Support for FreeType 2.9.0 is deprecated and will be removed in Pillow 12.0.0 (2025-10-15), when FreeType 2.9.1 will be the minimum supported.
We recommend upgrading to at least FreeType 2.10.4, which fixed a severe vulnerability introduced in FreeType 2.6 (CVE 2020-15999).
ICNS (width, height, scale) sizes¶
Deprecated since version 11.0.0.
Setting an ICNS image size to (width, height, scale) before loading has been
deprecated. Instead, load(scale) can be used.
Image isImageType()¶
Deprecated since version 11.0.0.
Image.isImageType(im) has been deprecated. Use isinstance(im, Image.Image)
instead.
ImageMath.lambda_eval and ImageMath.unsafe_eval options parameter¶
Deprecated since version 11.0.0.
The options parameter in lambda_eval() and
unsafe_eval() has been deprecated. One or more keyword
arguments can be used instead.
JpegImageFile.huffman_ac and JpegImageFile.huffman_dc¶
Deprecated since version 11.0.0.
The huffman_ac and huffman_dc dictionaries on JPEG images were unused. They
have been deprecated, and will be removed in Pillow 12 (2025-10-15).
Specific WebP feature checks¶
Deprecated since version 11.0.0.
features.check("transp_webp"), features.check("webp_mux") and
features.check("webp_anim") are now deprecated. They will always return
True if the WebP module is installed, until they are removed in Pillow
12.0.0 (2025-10-15).
Get internal pointers to objects¶
Deprecated since version 11.0.0.
Image.core.ImagingCore.id and Image.core.ImagingCore.unsafe_ptrs have been
deprecated and will be removed in Pillow 12 (2025-10-15). They were used for obtaining
raw pointers to ImagingCore internals. To interact with C code, you can use
Image.Image.getim(), which returns a Capsule object.
Image.Image.get_child_images()¶
Deprecated since version 11.2.1.
Image.Image.get_child_images() has been deprecated. and will be removed in Pillow
13 (2026-10-15). It will be moved to ImageFile.ImageFile.get_child_images(). The
method uses an image’s file pointer, and so child images could only be retrieved from
an PIL.ImageFile.ImageFile instance.
Removed features¶
Deprecated features are only removed in major releases after an appropriate period of deprecation has passed.
TiffImagePlugin IFD_LEGACY_API¶
Removed in version 11.0.0.
TiffImagePlugin.IFD_LEGACY_API was removed, as it was an unused setting.
PSFile¶
Deprecated since version 9.5.0.
Removed in version 11.0.0.
The PSFile class was removed in Pillow 11 (2024-10-15).
This class was only made as a helper to be used internally,
so there is no replacement. If you need this functionality though,
it is a very short class that can easily be recreated in your own code.
PyAccess and Image.USE_CFFI_ACCESS¶
Deprecated since version 10.0.0.
Removed in version 11.0.0.
Since Pillow’s C API is now faster than PyAccess on PyPy, PyAccess has been
removed. Pillow’s C API will now be used on PyPy instead.
Image.USE_CFFI_ACCESS, for switching from the C API to PyAccess, was
similarly removed.
Tk/Tcl 8.4¶
Deprecated since version 8.2.0.
Removed in version 10.0.0.
Support for Tk/Tcl 8.4 was removed in Pillow 10.0.0 (2023-07-01).
Categories¶
Deprecated since version 8.2.0.
Removed in version 10.0.0.
im.category was removed along with the related Image.NORMAL,
Image.SEQUENCE and Image.CONTAINER attributes.
To determine if an image has multiple frames or not,
getattr(im, "is_animated", False) can be used instead.
JpegImagePlugin.convert_dict_qtables¶
Deprecated since version 8.3.0.
Removed in version 10.0.0.
Since deprecation in Pillow 8.3.0, the convert_dict_qtables method no longer
performed any operations on the data given to it, and has been removed.
ImagePalette size parameter¶
Deprecated since version 8.4.0.
Removed in version 10.0.0.
Before Pillow 8.3.0, ImagePalette required palette data of particular lengths by
default, and the size parameter could be used to override that. Pillow 8.3.0
removed the default required length, also removing the need for the size parameter.
ImageShow.Viewer.show_file file argument¶
Deprecated since version 9.1.0.
Removed in version 10.0.0.
The file argument in show_file() has been
removed and replaced by path.
In effect, viewer.show_file("test.jpg") will continue to work unchanged.
Constants¶
Deprecated since version 9.1.0.
Removed in version 10.0.0.
A number of constants have been removed.
Instead, enum.IntEnum classes have been added.
Note
Additional Image constants were deprecated in Pillow 9.1.0, but that
was reversed in Pillow 9.4.0 and those constants will now remain available.
See Constants
Removed |
Use instead |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
FitsStubImagePlugin¶
Deprecated since version 9.1.0.
Removed in version 10.0.0.
The stub image plugin FitsStubImagePlugin has been removed.
FITS images can be read without a handler through FitsImagePlugin instead.
Font size and offset methods¶
Deprecated since version 9.2.0.
Removed in version 10.0.0.
Several functions for computing the size and offset of rendered text have been removed:
Removed |
Use instead |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
Previous code:
from PIL import Image, ImageDraw, ImageFont
font = ImageFont.truetype("Tests/fonts/FreeMono.ttf")
width, height = font.getsize("Hello world")
left, top = font.getoffset("Hello world")
im = Image.new("RGB", (100, 100))
draw = ImageDraw.Draw(im)
width, height = draw.textsize("Hello world", font)
width, height = font.getsize_multiline("Hello\nworld")
width, height = draw.multiline_textsize("Hello\nworld", font)
Use instead:
from PIL import Image, ImageDraw, ImageFont
font = ImageFont.truetype("Tests/fonts/FreeMono.ttf")
left, top, right, bottom = font.getbbox("Hello world")
width, height = right - left, bottom - top
im = Image.new("RGB", (100, 100))
draw = ImageDraw.Draw(im)
width = draw.textlength("Hello world", font)
left, top, right, bottom = draw.multiline_textbbox((0, 0), "Hello\nworld", font)
width, height = right - left, bottom - top
Previously, the size methods returned a height that included the vertical
offset of the text, while the new bbox methods distinguish this as a top
offset.
If you are using these methods for aligning text, consider using Text anchors instead which avoid issues that can occur with non-English text or unusual fonts. For example, instead of the following code:
from PIL import Image, ImageDraw, ImageFont
font = ImageFont.truetype("Tests/fonts/FreeMono.ttf")
im = Image.new("RGB", (100, 100))
draw = ImageDraw.Draw(im)
width, height = draw.textsize("Hello world", font)
x, y = (100 - width) / 2, (100 - height) / 2
draw.text((x, y), "Hello world", font=font)
Use instead:
from PIL import Image, ImageDraw, ImageFont
font = ImageFont.truetype("Tests/fonts/FreeMono.ttf")
im = Image.new("RGB", (100, 100))
draw = ImageDraw.Draw(im)
draw.text((100 / 2, 100 / 2), "Hello world", font=font, anchor="mm")
FreeTypeFont.getmask2 fill parameter¶
Deprecated since version 9.2.0.
Removed in version 10.0.0.
The undocumented fill parameter of FreeTypeFont.getmask2() has been
removed.
PhotoImage.paste box parameter¶
Deprecated since version 9.2.0.
Removed in version 10.0.0.
The box parameter was unused and has been removed.
PyQt5 and PySide2¶
Deprecated since version 9.2.0.
Removed in version 10.0.0.
Qt 5 reached end-of-life on 2020-12-08 for open-source users (and will reach EOL on 2023-12-08 for commercial licence holders).
Support for PyQt5 and PySide2 has been removed from ImageQt. Upgrade to
PyQt6 or
PySide6 instead.
Image.coerce_e¶
Deprecated since version 9.2.0.
Removed in version 10.0.0.
This undocumented method has been removed.
PILLOW_VERSION constant¶
Deprecated since version 5.2.0.
Removed in version 9.0.0.
Use __version__ instead.
It was initially removed in Pillow 7.0.0, but temporarily brought back in 7.1.0 to give projects more time to upgrade.
Image.show command parameter¶
Deprecated since version 7.2.0.
Removed in version 9.0.0.
The command parameter has been removed. Use a subclass of
ImageShow.Viewer instead.
Image._showxv¶
Deprecated since version 7.2.0.
Removed in version 9.0.0.
Use Image.Image.show() instead. If custom behaviour is required, use
ImageShow.register() to add a custom ImageShow.Viewer class.
ImageFile.raise_ioerror¶
Deprecated since version 7.2.0.
Removed in version 9.0.0.
IOError was merged into OSError in Python 3.3.
So, ImageFile.raise_ioerror has been removed.
Use ImageFile.raise_oserror instead.
FreeType 2.7¶
Deprecated since version 8.1.0.
Removed in version 9.0.0.
Support for FreeType 2.7 has been removed.
We recommend upgrading to at least FreeType 2.10.4, which fixed a severe vulnerability introduced in FreeType 2.6 (CVE 2020-15999).
im.offset¶
Deprecated since version 1.1.2.
Removed in version 8.0.0.
im.offset() has been removed, call ImageChops.offset() instead.
It was documented as deprecated in PIL 1.1.2,
raised a DeprecationWarning since 1.1.5,
an Exception since Pillow 3.0.0
and NotImplementedError since 3.3.0.
Image.fromstring, im.fromstring and im.tostring¶
Deprecated since version 2.0.0.
Removed in version 8.0.0.
Image.fromstring()has been removed, callImage.frombytes()instead.im.fromstring()has been removed, callfrombytes()instead.im.tostring()has been removed, calltobytes()instead.
They issued a DeprecationWarning since 2.0.0,
an Exception since 3.0.0
and NotImplementedError since 3.3.0.
ImageCms.CmsProfile attributes¶
Deprecated since version 3.2.0.
Removed in version 8.0.0.
Some attributes in PIL.ImageCms.core.CmsProfile have been removed.
From 6.0.0, they issued a DeprecationWarning:
Removed |
Use instead |
|---|---|
|
Padded |
|
Padded |
|
Unicode |
|
Unicode |
|
Unicode |
|
Unicode |
|
Unicode |
Python 2.7¶
Deprecated since version 6.0.0.
Removed in version 7.0.0.
Python 2.7 reached end-of-life on 2020-01-01. Pillow 6.x was the last series to support Python 2.
Image.__del__¶
Deprecated since version 6.1.0.
Removed in version 7.0.0.
Implicitly closing the image’s underlying file in Image.__del__ has been removed.
Use a context manager or call Image.close() instead to close the file in a
deterministic way.
Previous method:
im = Image.open("hopper.png")
im.save("out.jpg")
Use instead:
with Image.open("hopper.png") as im:
im.save("out.jpg")
PIL.*ImagePlugin.__version__ attributes¶
Deprecated since version 6.0.0.
Removed in version 7.0.0.
The version constants of individual plugins have been removed. Use PIL.__version__
instead.
Removed |
Removed |
Removed |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
PyQt4 and PySide¶
Deprecated since version 6.0.0.
Removed in version 7.0.0.
Qt 4 reached end-of-life on 2015-12-19. Its Python bindings are also EOL: PyQt4 since 2018-08-31 and PySide since 2015-10-14.
Support for PyQt4 and PySide has been removed from ImageQt. Please upgrade to PyQt5
or PySide2.
Setting the size of TIFF images¶
Deprecated since version 5.3.0.
Removed in version 7.0.0.
Setting the size of a TIFF image directly (eg. im.size = (256, 256)) throws
an error. Use Image.resize instead.
VERSION constant¶
Deprecated since version 5.2.0.
Removed in version 6.0.0.
VERSION (the old PIL version, always 1.1.7) has been removed. Use
__version__ instead.
Undocumented ImageOps functions¶
Deprecated since version 4.3.0.
Removed in version 6.0.0.
Several undocumented functions in ImageOps have been removed. Use the equivalents
in ImageFilter instead:
Removed |
Use instead |
|---|---|
|
|
|
|
|
|
|
|
|
|
PIL.OleFileIO¶
Deprecated since version 4.0.0.
Removed in version 6.0.0.
PIL.OleFileIO was removed as a vendored file in Pillow 4.0.0 (2017-01) in favour of
the upstream olefile Python package, and replaced with an ImportError in 5.0.0
(2018-01). The deprecated file has now been removed from Pillow. If needed, install from
PyPI (eg. python3 -m pip install olefile).
import _imaging¶
Removed in version 2.1.0.
Pillow >= 2.1.0 no longer supports import _imaging.
Please use from PIL.Image import core as _imaging instead.
Pillow and PIL¶
Removed in version 1.0.0.
Pillow and PIL cannot co-exist in the same environment. Before installing Pillow, please uninstall PIL.
import Image¶
Removed in version 1.0.0.
Pillow >= 1.0 no longer supports import Image.
Please use from PIL import Image instead.