9.1.0

Deprecations

Constants ^^^^^^^^^

A number of constants have been deprecated and will be removed in Pillow 10.0.0 (2023-07-01). Instead, :py:class:enum.IntEnum classes have been added.

.. note::

Some of these deprecations were restored in Pillow 9.4.0. See
:ref:`restored-image-constants`

============================== Deprecated ============================== Image.NONE Image.NEAREST Image.ORDERED Image.RASTERIZE Image.FLOYDSTEINBERG Image.WEB Image.ADAPTIVE Image.AFFINE Image.EXTENT Image.PERSPECTIVE Image.QUAD Image.MESH Image.FLIP_LEFT_RIGHT Image.FLIP_TOP_BOTTOM Image.ROTATE_90 Image.ROTATE_180 Image.ROTATE_270 Image.TRANSPOSE Image.TRANSVERSE Image.BOX Image.BILINEAR Image.LINEAR Image.HAMMING Image.BICUBIC Image.CUBIC Image.LANCZOS Image.ANTIALIAS Image.MEDIANCUT Image.MAXCOVERAGE Image.FASTOCTREE Image.LIBIMAGEQUANT ImageCms.INTENT_PERCEPTUAL ImageCms.INTENT_RELATIVE ImageCms.INTENT_SATURATION ImageCms.INTENT_ABSOLUTE ImageCms.DIRECTION_INPUT ImageCms.DIRECTION_OUTPUT ImageCms.DIRECTION_PROOF ImageFont.LAYOUT_BASIC ImageFont.LAYOUT_RAQM BlpImagePlugin.BLP_FORMAT_JPEG BlpImagePlugin.BLP_ENCOD BlpImagePlugin.BLP_ENCOD BlpImagePlugin.BLP_ENCOD BlpImagePlugin.BLP_ALPHA BlpImagePlugin.BLP_ALPHA BlpImagePlugin.BLP_ALPHA FtexImagePlugin.FORMAT_DXT1 FtexImagePlugin.FORMAT_U PngImagePlugin.APNG_DISP PngImagePlugin.APNG_DISP PngImagePlugin.APNG_DISP PngImagePlugin.APNG_BLEN PngImagePlugin.APNG_BLEN ============================== ======================= ============================================================ Use instead ======================= ============================================================ Either Image.Dither.NONE or Image.Resampling.NEAREST Either Image.Dither.NONE or Image.Resampling.NEAREST Image.Dither.ORDERED Image.Dither.RASTERIZE Image.Dither.FLOYDSTEINBERG Image.Palette.WEB Image.Palette.ADAPTIVE Image.Transform.AFFINE Image.Transform.EXTENT Image.Transform.PERSPECTIVE Image.Transform.QUAD Image.Transform.MESH Image.Transpose.FLIP_LEFT_RIGHT Image.Transpose.FLIP_TOP_BOTTOM Image.Transpose.ROTATE_90 Image.Transpose.ROTATE_180 Image.Transpose.ROTATE_270 Image.Transpose.TRANSPOSE Image.Transpose.TRANSVERSE Image.Resampling.BOX Image.Resampling.BILINEAR Image.Resampling.BILINEAR Image.Resampling.HAMMING Image.Resampling.BICUBIC Image.Resampling.BICUBIC Image.Resampling.LANCZOS Image.Resampling.LANCZOS Image.Quantize.MEDIANCUT Image.Quantize.MAXCOVERAGE Image.Quantize.FASTOCTREE Image.Quantize.LIBIMAGEQUANT ImageCms.Intent.PERCEPTUAL _COLORMETRIC ImageCms.Intent.RELATIVE_COLORMETRIC ImageCms.Intent.SATURATION _COLORIMETRIC ImageCms.Intent.ABSOLUTE_COLORIMETRIC ImageCms.Direction.INPUT ImageCms.Direction.OUTPUT ImageCms.Direction.PROOF ImageFont.Layout.BASIC ImageFont.Layout.RAQM BlpImagePlugin.Format.JPEG ING_UNCOMPRESSED BlpImagePlugin.Encoding.UNCOMPRESSED ING_DXT BlpImagePlugin.Encoding.DXT ING_UNCOMPRESSED_RAW_RGBA BlpImagePlugin.Encoding.UNCOMPRESSED_RAW_RGBA _ENCODING_DXT1 BlpImagePlugin.AlphaEncoding.DXT1 _ENCODING_DXT3 BlpImagePlugin.AlphaEncoding.DXT3 _ENCODING_DXT5 BlpImagePlugin.AlphaEncoding.DXT5 FtexImagePlugin.Format.DXT1 NCOMPRESSED FtexImagePlugin.Format.UNCOMPRESSED OSE_OP_NONE PngImagePlugin.Disposal.OP_NONE OSE_OP_BACKGROUND PngImagePlugin.Disposal.OP_BACKGROUND OSE_OP_PREVIOUS PngImagePlugin.Disposal.OP_PREVIOUS D_OP_SOURCE PngImagePlugin.Blend.OP_SOURCE D_OP_OVER PngImagePlugin.Blend.OP_OVER ======================= ============================================================

ImageShow.Viewer.show_file file argument ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The file argument in :py:meth:~PIL.ImageShow.Viewer.show_file() has been deprecated and will be removed in Pillow 10.0.0 (2023-07-01). It has been replaced by path.

In effect, viewer.show_file("test.jpg") will continue to work unchanged. viewer.show_file(file="test.jpg") will raise a deprecation warning, and suggest viewer.show_file(path="test.jpg") instead.

FitsStubImagePlugin ^^^^^^^^^^^^^^^^^^^

.. deprecated:: 9.1.0

The stub image plugin FitsStubImagePlugin has been deprecated and will be removed in Pillow 10.0.0 (2023-07-01). FITS images can be read without a handler through :mod:~PIL.FitsImagePlugin instead.

API changes

Raise an error when performing a negative crop ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Performing a negative crop on an image previously just returned a (0, 0) image. Now it will raise a :py:exc:ValueError, to help reduce confusion if a user has unintentionally provided the wrong arguments.

Added specific error if path coordinate type is incorrect ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Rather than returning a :py:exc:SystemError, passing the incorrect types of coordinates into a path will now raise a more specific :py:exc:ValueError, with the message "incorrect coordinate type".

Replace requirements.txt with extras ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Rather than installing all dependencies for docs and tests via requirements.txt, extras_require is used instead. This installs only those needed and at the same time as installing Pillow.

For example:

.. code-block:: bash

# Install with dependencies for tests:
python3 -m pip install .[tests]

# Or for building docs:
python3 -m pip install .[docs]

# Or for all:
python3 -m pip install .[docs,tests]

On macOS, the last argument may need to be wrapped in quotes, e.g. python3 -m pip install ".[tests]"

Therefore requirements.txt has been removed along with the make install-req command for installing its contents.

API additions

Added get_photoshop_blocks() to parse Photoshop TIFF tag ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

:py:meth:~PIL.TiffImagePlugin.TiffImageFile.get_photoshop_blocks has been added, to allow users to determine what Photoshop "Image Resource Blocks" are contained within an image. The keys of the returned dictionary are the image resource IDs.

At present, the information within each block is merely returned as a dictionary with a "data" entry. This will allow more useful information to be added in the future without breaking backwards compatibility.

Added mct and no_jp2 options for saving JPEG 2000 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The :py:meth:PIL.Image.Image.save method now supports the following options for JPEG 2000:

mct If 1 then enable multiple component transformation when encoding, otherwise use 0 for no component transformation (default). If MCT is enabled and irreversible is True then the Irreversible Color Transformation will be applied, otherwise encoding will use the Reversible Color Transformation. MCT works best with a mode of RGB and is only applicable when the image data has 3 components.

no_jp2 If True then don't wrap the raw codestream in the JP2 file format when saving, otherwise the extension of the filename will be used to determine the format (default).

Added PyEncoder ^^^^^^^^^^^^^^^

:py:class:~PIL.ImageFile.PyEncoder has been added, allowing for file encoders to be written in Python. See :ref:Writing Your Own File Codec in Python<file-codecs-py> for more information.

GifImagePlugin loading strategy ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Pillow 9.0.0 introduced the conversion of subsequent GIF frames to RGB or RGBA. This behaviour can now be changed so that the first P frame is converted to RGB as well. ::

from PIL import GifImagePlugin
GifImagePlugin.LOADING_STRATEGY = GifImagePlugin.LoadingStrategy.RGB_ALWAYS

Or subsequent frames can be kept in P mode as long as there is only a single palette. ::

from PIL import GifImagePlugin
GifImagePlugin.LOADING_STRATEGY = GifImagePlugin.LoadingStrategy.RGB_AFTER_DIFFERENT_PALETTE_ONLY

Other changes

musllinux wheels ^^^^^^^^^^^^^^^^

Pillow now builds binary wheels for musllinux, suitable for Linux distributions based on the musl C standard library such as Alpine (rather than the glibc library used by manylinux wheels). See :pep:656.

ImageShow temporary files on Unix ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

When calling :py:meth:~PIL.Image.Image.show or using :py:mod:~PIL.ImageShow, a temporary file is created from the image. On Unix, Pillow will no longer delete these files, and instead leave it to the operating system to do so.

Image.repr_pretty ^^^^^^^^^^^^^^^^^^^

im._repr_pretty_ has been added to provide a representation of an image without the identity of the object. This allows Jupyter to describe an image and have that description stay the same on subsequent executions of the same code.

Added BigTIFF reading ^^^^^^^^^^^^^^^^^^^^^

Support has been added for reading BigTIFF images.

Added BLP saving ^^^^^^^^^^^^^^^^

Support has been added for saving BLP images. blp_version can be used to specify whether the image should be saved as BLP1 or BLP2, e.g. im.save("out.blp", blp_version="BLP1"). By default, BLP2 will be used.