2018-12-06 11:56:07 +03:00
.. _deprecations:
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,
2023-11-01 21:18:25 +03:00
a :py:exc: `DeprecationWarning` is issued.
2018-12-06 11:56:07 +03:00
2023-03-29 18:30:20 +03:00
PSFile
~~~~~~
.. deprecated :: 9.5.0
The :py:class: `~PIL.EpsImagePlugin.PSFile` class has been deprecated and will
be 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.
2023-06-29 01:30:10 +03:00
PyAccess and Image.USE_CFFI_ACCESS
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2023-06-28 13:10:10 +03:00
.. deprecated :: 10.0.0
Since Pillow's C API is now faster than PyAccess on PyPy,
:py:mod: `~PIL.PyAccess` has been deprecated and will be removed in Pillow
2023-06-28 15:00:32 +03:00
11.0.0 (2024-10-15). Pillow's C API will now be used by default on PyPy instead.
2023-06-28 13:10:10 +03:00
2023-06-29 01:30:10 +03:00
`` Image.USE_CFFI_ACCESS `` , for switching from the C API to PyAccess, is
similarly deprecated.
2020-07-09 13:19:19 +03:00
Removed features
----------------
Deprecated features are only removed in major releases after an appropriate
period of deprecation has passed.
2023-04-02 19:32:26 +03:00
Tk/Tcl 8.4
~~~~~~~~~~
.. deprecated :: 8.2.0
.. versionremoved :: 10.0.0
Support for Tk/Tcl 8.4 was removed in Pillow 10.0.0 (2023-07-01).
2023-04-02 19:51:16 +03:00
Categories
~~~~~~~~~~
.. deprecated :: 8.2.0
.. versionremoved :: 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.
2023-04-02 20:27:30 +03:00
JpegImagePlugin.convert_dict_qtables
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. deprecated :: 8.3.0
.. versionremoved :: 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.
2023-04-02 20:45:51 +03:00
ImagePalette size parameter
~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. deprecated :: 8.4.0
.. versionremoved :: 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.
2023-04-02 20:54:59 +03:00
ImageShow.Viewer.show_file file argument
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. deprecated :: 9.1.0
.. versionremoved :: 10.0.0
The `` file `` argument in :py:meth: `~PIL.ImageShow.Viewer.show_file()` has been
removed and replaced by `` path `` .
In effect, `` viewer.show_file("test.jpg") `` will continue to work unchanged.
2023-04-02 21:19:11 +03:00
Constants
~~~~~~~~~
.. deprecated :: 9.1.0
.. versionremoved :: 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 :ref: `restored-image-constants`
===================================================== ============================================================
Removed Use instead
===================================================== ============================================================
`` Image.LINEAR `` `` Image.BILINEAR `` or `` Image.Resampling.BILINEAR ``
`` Image.CUBIC `` `` Image.BICUBIC `` or `` Image.Resampling.BICUBIC ``
`` Image.ANTIALIAS `` `` Image.LANCZOS `` or `` Image.Resampling.LANCZOS ``
`` ImageCms.INTENT_PERCEPTUAL `` `` ImageCms.Intent.PERCEPTUAL ``
`` ImageCms.INTENT_RELATIVE_COLORMETRIC `` `` ImageCms.Intent.RELATIVE_COLORMETRIC ``
`` ImageCms.INTENT_SATURATION `` `` ImageCms.Intent.SATURATION ``
`` ImageCms.INTENT_ABSOLUTE_COLORIMETRIC `` `` ImageCms.Intent.ABSOLUTE_COLORIMETRIC ``
`` ImageCms.DIRECTION_INPUT `` `` ImageCms.Direction.INPUT ``
`` ImageCms.DIRECTION_OUTPUT `` `` ImageCms.Direction.OUTPUT ``
`` ImageCms.DIRECTION_PROOF `` `` ImageCms.Direction.PROOF ``
`` ImageFont.LAYOUT_BASIC `` `` ImageFont.Layout.BASIC ``
`` ImageFont.LAYOUT_RAQM `` `` ImageFont.Layout.RAQM ``
`` BlpImagePlugin.BLP_FORMAT_JPEG `` `` BlpImagePlugin.Format.JPEG ``
`` BlpImagePlugin.BLP_ENCODING_UNCOMPRESSED `` `` BlpImagePlugin.Encoding.UNCOMPRESSED ``
`` BlpImagePlugin.BLP_ENCODING_DXT `` `` BlpImagePlugin.Encoding.DXT ``
`` BlpImagePlugin.BLP_ENCODING_UNCOMPRESSED_RAW_RGBA `` `` BlpImagePlugin.Encoding.UNCOMPRESSED_RAW_RGBA ``
`` BlpImagePlugin.BLP_ALPHA_ENCODING_DXT1 `` `` BlpImagePlugin.AlphaEncoding.DXT1 ``
`` BlpImagePlugin.BLP_ALPHA_ENCODING_DXT3 `` `` BlpImagePlugin.AlphaEncoding.DXT3 ``
`` BlpImagePlugin.BLP_ALPHA_ENCODING_DXT5 `` `` BlpImagePlugin.AlphaEncoding.DXT5 ``
`` FtexImagePlugin.FORMAT_DXT1 `` `` FtexImagePlugin.Format.DXT1 ``
`` FtexImagePlugin.FORMAT_UNCOMPRESSED `` `` FtexImagePlugin.Format.UNCOMPRESSED ``
`` PngImagePlugin.APNG_DISPOSE_OP_NONE `` `` PngImagePlugin.Disposal.OP_NONE ``
`` PngImagePlugin.APNG_DISPOSE_OP_BACKGROUND `` `` PngImagePlugin.Disposal.OP_BACKGROUND ``
`` PngImagePlugin.APNG_DISPOSE_OP_PREVIOUS `` `` PngImagePlugin.Disposal.OP_PREVIOUS ``
`` PngImagePlugin.APNG_BLEND_OP_SOURCE `` `` PngImagePlugin.Blend.OP_SOURCE ``
`` PngImagePlugin.APNG_BLEND_OP_OVER `` `` PngImagePlugin.Blend.OP_OVER ``
===================================================== ============================================================
2023-04-02 21:32:18 +03:00
FitsStubImagePlugin
~~~~~~~~~~~~~~~~~~~
.. deprecated :: 9.1.0
.. versionremoved :: 10.0.0
The stub image plugin `` FitsStubImagePlugin `` has been removed.
FITS images can be read without a handler through :mod: `~PIL.FitsImagePlugin` instead.
2023-04-05 12:10:51 +03:00
Font size and offset methods
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. deprecated :: 9.2.0
.. versionremoved :: 10.0.0
Several functions for computing the size and offset of rendered text have been removed:
=============================================================== =============================================================================================================
Removed Use instead
=============================================================== =============================================================================================================
`` FreeTypeFont.getsize() `` and `` FreeTypeFont.getoffset() `` :py:meth: `.FreeTypeFont.getbbox` and :py:meth: `.FreeTypeFont.getlength`
`` FreeTypeFont.getsize_multiline() `` :py:meth: `.ImageDraw.multiline_textbbox`
`` ImageFont.getsize() `` :py:meth: `.ImageFont.getbbox` and :py:meth: `.ImageFont.getlength`
`` TransposedFont.getsize() `` :py:meth: `.TransposedFont.getbbox` and :py:meth: `.TransposedFont.getlength`
`` ImageDraw.textsize() `` and `` ImageDraw.multiline_textsize() `` :py:meth: `.ImageDraw.textbbox` , :py:meth: `.ImageDraw.textlength` and :py:meth: `.ImageDraw.multiline_textbbox`
`` ImageDraw2.Draw.textsize() `` :py:meth: `.ImageDraw2.Draw.textbbox` and :py:meth: `.ImageDraw2.Draw.textlength`
=============================================================== =============================================================================================================
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")
width, height = font.getsize_multiline("Hello\nworld")
width, height = draw.multiline_textsize("Hello\nworld")
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")
left, top, right, bottom = draw.multiline_textbbox((0, 0), "Hello\nworld")
width, height = right - left, bottom - top
2023-04-02 21:40:39 +03:00
FreeTypeFont.getmask2 fill parameter
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. deprecated :: 9.2.0
.. versionremoved :: 10.0.0
The undocumented `` fill `` parameter of :py:meth: `.FreeTypeFont.getmask2` has been
removed.
2023-04-02 21:54:51 +03:00
PhotoImage.paste box parameter
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. deprecated :: 9.2.0
.. versionremoved :: 10.0.0
The `` box `` parameter was unused and has been removed.
2023-04-02 00:27:22 +03:00
PyQt5 and PySide2
~~~~~~~~~~~~~~~~~
.. deprecated :: 9.2.0
.. versionremoved :: 10.0.0
`Qt 5 reached end-of-life <https://www.qt.io/blog/qt-5.15-released> `_ 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 <https://www.riverbankcomputing.com/static/Docs/PyQt6/> `_ or
2023-05-11 01:13:33 +03:00
`PySide6 <https://doc.qt.io/qtforpython-6/> `_ instead.
2023-04-02 00:27:22 +03:00
2023-04-02 22:16:13 +03:00
Image.coerce_e
~~~~~~~~~~~~~~
.. deprecated :: 9.2.0
.. versionremoved :: 10.0.0
This undocumented method has been removed.
2021-10-18 09:20:56 +03:00
PILLOW_VERSION constant
~~~~~~~~~~~~~~~~~~~~~~~
.. deprecated :: 5.2.0
.. versionremoved :: 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.
2021-10-18 03:08:51 +03:00
Image.show command parameter
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. deprecated :: 7.2.0
.. versionremoved :: 9.0.0
The `` command `` parameter has been removed. Use a subclass of
:py:class: `.ImageShow.Viewer` instead.
2021-10-18 02:53:48 +03:00
Image._showxv
~~~~~~~~~~~~~
.. deprecated :: 7.2.0
.. versionremoved :: 9.0.0
Use :py:meth: `.Image.Image.show` instead. If custom behaviour is required, use
:py:func: `.ImageShow.register` to add a custom :py:class: `.ImageShow.Viewer` class.
2021-10-18 02:53:16 +03:00
ImageFile.raise_ioerror
~~~~~~~~~~~~~~~~~~~~~~~
.. deprecated :: 7.2.0
.. versionremoved :: 9.0.0
2023-11-01 21:18:25 +03:00
:py:exc: `IOError` was merged into :py:exc: `OSError` in Python 3.3.
2021-10-18 02:53:16 +03:00
So, `` ImageFile.raise_ioerror `` has been removed.
Use `` ImageFile.raise_oserror `` instead.
2021-10-17 23:29:41 +03:00
FreeType 2.7
~~~~~~~~~~~~
.. deprecated :: 8.1.0
.. versionremoved :: 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
2023-03-08 19:07:14 +03:00
vulnerability introduced in FreeType 2.6 (:cve: `2020-15999` ).
2021-10-17 23:29:41 +03:00
2022-09-23 15:13:50 +03:00
.. _FreeType: https://freetype.org/
2021-10-17 23:29:41 +03:00
2020-07-17 10:55:20 +03:00
im.offset
~~~~~~~~~
.. deprecated :: 1.1.2
.. versionremoved :: 8.0.0
2020-08-09 20:08:38 +03:00
`` im.offset() `` has been removed, call :py:func: `.ImageChops.offset()` instead.
2020-07-17 10:55:20 +03:00
It was documented as deprecated in PIL 1.1.2,
2023-11-01 21:18:25 +03:00
raised a :py:exc: `DeprecationWarning` since 1.1.5,
an :py:exc: `Exception` since Pillow 3.0.0
and :py:exc: `NotImplementedError` since 3.3.0.
2020-07-17 10:55:20 +03:00
2020-07-21 15:55:32 +03:00
Image.fromstring, im.fromstring and im.tostring
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2020-07-17 10:55:20 +03:00
.. deprecated :: 2.0.0
.. versionremoved :: 8.0.0
2020-07-18 10:09:15 +03:00
* `` Image.fromstring() `` has been removed, call :py:func: `.Image.frombytes()` instead.
* `` im.fromstring() `` has been removed, call :py:meth: `~PIL.Image.Image.frombytes()` instead.
* `` im.tostring() `` has been removed, call :py:meth: `~PIL.Image.Image.tobytes()` instead.
2020-07-17 10:55:20 +03:00
2023-11-01 21:18:25 +03:00
They issued a :py:exc: `DeprecationWarning` since 2.0.0,
an :py:exc: `Exception` since 3.0.0
and :py:exc: `NotImplementedError` since 3.3.0.
2020-07-17 10:55:20 +03:00
2019-01-28 15:30:27 +03:00
ImageCms.CmsProfile attributes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. deprecated :: 3.2.0
2020-07-09 13:19:19 +03:00
.. versionremoved :: 8.0.0
2019-01-28 15:30:27 +03:00
2020-08-09 20:08:38 +03:00
Some attributes in :py:class: `PIL.ImageCms.CmsProfile` have been removed. From 6.0.0,
2023-11-01 21:18:25 +03:00
they issued a :py:exc: `DeprecationWarning` :
2019-01-28 15:30:27 +03:00
2020-08-09 22:48:44 +03:00
======================== ===================================================
2020-07-09 13:19:19 +03:00
Removed Use instead
2020-08-09 22:48:44 +03:00
======================== ===================================================
2020-08-09 21:44:51 +03:00
`` color_space `` Padded :py:attr: `~.CmsProfile.xcolor_space`
`` pcs `` Padded :py:attr: `~.CmsProfile.connection_space`
`` product_copyright `` Unicode :py:attr: `~.CmsProfile.copyright`
`` product_desc `` Unicode :py:attr: `~.CmsProfile.profile_description`
`` product_description `` Unicode :py:attr: `~.CmsProfile.profile_description`
`` product_manufacturer `` Unicode :py:attr: `~.CmsProfile.manufacturer`
`` product_model `` Unicode :py:attr: `~.CmsProfile.model`
2020-08-09 22:48:44 +03:00
======================== ===================================================
2019-01-28 15:30:27 +03:00
2019-12-31 15:12:01 +03:00
Python 2.7
~~~~~~~~~~
2020-07-09 12:46:44 +03:00
.. deprecated :: 6.0.0
2020-07-09 12:24:23 +03:00
.. versionremoved :: 7.0.0
2019-12-31 15:12:01 +03:00
Python 2.7 reached end-of-life on 2020-01-01. Pillow 6.x was the last series to
support Python 2.
2019-11-01 14:42:12 +03:00
Image.__del__
~~~~~~~~~~~~~
2020-07-09 12:46:44 +03:00
.. deprecated :: 6.1.0
2020-07-09 12:24:23 +03:00
.. versionremoved :: 7.0.0
2019-11-01 14:42:12 +03:00
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.
2023-02-18 12:34:52 +03:00
Previous method::
2019-11-01 14:42:12 +03:00
im = Image.open("hopper.png")
im.save("out.jpg")
2023-02-18 12:34:52 +03:00
Use instead::
2019-11-01 14:42:12 +03:00
with Image.open("hopper.png") as im:
im.save("out.jpg")
2019-11-05 18:00:51 +03:00
PIL.*ImagePlugin.__version__ attributes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2020-07-09 12:46:44 +03:00
.. deprecated :: 6.0.0
2020-07-09 12:24:23 +03:00
.. versionremoved :: 7.0.0
2019-11-05 18:00:51 +03:00
The version constants of individual plugins have been removed. Use `` PIL.__version__ ``
instead.
=============================== ================================= ==================================
2019-11-05 23:04:04 +03:00
Removed Removed Removed
2019-11-05 18:00:51 +03:00
=============================== ================================= ==================================
`` BmpImagePlugin.__version__ `` `` Jpeg2KImagePlugin.__version__ `` `` PngImagePlugin.__version__ ``
`` CurImagePlugin.__version__ `` `` JpegImagePlugin.__version__ `` `` PpmImagePlugin.__version__ ``
`` DcxImagePlugin.__version__ `` `` McIdasImagePlugin.__version__ `` `` PsdImagePlugin.__version__ ``
`` EpsImagePlugin.__version__ `` `` MicImagePlugin.__version__ `` `` SgiImagePlugin.__version__ ``
`` FliImagePlugin.__version__ `` `` MpegImagePlugin.__version__ `` `` SunImagePlugin.__version__ ``
`` FpxImagePlugin.__version__ `` `` MpoImagePlugin.__version__ `` `` TgaImagePlugin.__version__ ``
`` GdImageFile.__version__ `` `` MspImagePlugin.__version__ `` `` TiffImagePlugin.__version__ ``
`` GifImagePlugin.__version__ `` `` PalmImagePlugin.__version__ `` `` WmfImagePlugin.__version__ ``
`` IcoImagePlugin.__version__ `` `` PcdImagePlugin.__version__ `` `` XbmImagePlugin.__version__ ``
`` ImImagePlugin.__version__ `` `` PcxImagePlugin.__version__ `` `` XpmImagePlugin.__version__ ``
`` ImtImagePlugin.__version__ `` `` PdfImagePlugin.__version__ `` `` XVThumbImagePlugin.__version__ ``
`` IptcImagePlugin.__version__ `` `` PixarImagePlugin.__version__ ``
=============================== ================================= ==================================
2019-09-26 21:38:19 +03:00
PyQt4 and PySide
~~~~~~~~~~~~~~~~
2020-07-09 12:46:44 +03:00
.. deprecated :: 6.0.0
2020-07-09 12:24:23 +03:00
.. versionremoved :: 7.0.0
2019-09-26 21:38:19 +03:00
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.
2019-10-03 15:12:28 +03:00
Setting the size of TIFF images
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2020-07-09 12:46:44 +03:00
.. deprecated :: 5.3.0
2020-07-09 12:24:23 +03:00
.. versionremoved :: 7.0.0
2019-10-03 15:12:28 +03:00
Setting the size of a TIFF image directly (eg. `` im.size = (256, 256) `` ) throws
an error. Use `` Image.resize `` instead.
2019-03-02 10:22:34 +03:00
VERSION constant
~~~~~~~~~~~~~~~~
2020-07-09 12:46:44 +03:00
.. deprecated :: 5.2.0
2020-07-09 12:24:23 +03:00
.. versionremoved :: 6.0.0
2019-03-02 10:22:34 +03:00
`` VERSION `` (the old PIL version, always 1.1.7) has been removed. Use
`` __version__ `` instead.
2018-12-06 11:56:07 +03:00
Undocumented ImageOps functions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2020-07-09 12:46:44 +03:00
.. deprecated :: 4.3.0
2020-07-09 12:24:23 +03:00
.. versionremoved :: 6.0.0
2018-12-06 11:56:07 +03:00
2019-01-20 23:07:22 +03:00
Several undocumented functions in `` ImageOps `` have been removed. Use the equivalents
in `` ImageFilter `` instead:
2018-12-06 11:56:07 +03:00
========================== ============================
2019-01-20 23:07:22 +03:00
Removed Use instead
2018-12-06 11:56:07 +03:00
========================== ============================
`` ImageOps.box_blur `` `` ImageFilter.BoxBlur ``
`` ImageOps.gaussian_blur `` `` ImageFilter.GaussianBlur ``
`` ImageOps.gblur `` `` ImageFilter.GaussianBlur ``
`` ImageOps.usm `` `` ImageFilter.UnsharpMask ``
`` ImageOps.unsharp_mask `` `` ImageFilter.UnsharpMask ``
========================== ============================
PIL.OleFileIO
~~~~~~~~~~~~~
2020-07-09 12:46:44 +03:00
.. deprecated :: 4.0.0
2020-07-09 12:24:23 +03:00
.. versionremoved :: 6.0.0
2018-12-06 11:56:07 +03:00
2023-11-01 21:18:25 +03:00
`` PIL.OleFileIO `` was removed as a vendored file in Pillow 4.0.0 (2017-01) in favour of
the upstream :pypi: `olefile` Python package, and replaced with an :py:exc: `ImportError` in 5.0.0
2019-01-20 23:07:22 +03:00
(2018-01). The deprecated file has now been removed from Pillow. If needed, install from
2020-03-09 14:39:27 +03:00
PyPI (eg. `` python3 -m pip install olefile `` ).
