Pillow (PIL Fork) Documentation Release 6.2.0.dev0 Alex Clark Jul 07, 2019 Contents 1 Installation 3 1.1 Warnings.................................................3 1.2 Notes...................................................3 1.3 Basic Installation.............................................4 1.4 Building From Source..........................................5 1.5 Platform Support.............................................9 1.6 Old Versions............................................... 10 2 Handbook 11 2.1 Overview................................................. 11 2.2 Tutorial.................................................. 12 2.3 Concepts................................................. 20 2.4 Appendices................................................ 21 3 Reference 45 3.1 Image Module.............................................. 45 3.2 ImageChops (“Channel Operations”) Module............................. 61 3.3 ImageColor Module.......................................... 64 3.4 ImageCms Module........................................... 65 3.5 ImageDraw Module.......................................... 78 3.6 ImageEnhance Module........................................ 85 3.7 ImageFile Module.......................................... 86 3.8 ImageFilter Module......................................... 88 3.9 ImageFont Module.......................................... 91 3.10 ImageGrab Module (macOS and Windows only)........................... 96 3.11 ImageMath Module.......................................... 97 3.12 ImageMorph Module.......................................... 99 3.13 ImageOps Module........................................... 100 3.14 ImagePalette Module........................................ 103 3.15 ImagePath Module.......................................... 104 3.16 ImageQt Module............................................ 105 3.17 ImageSequence Module....................................... 105 3.18 ImageStat Module.......................................... 105 3.19 ImageTk Module............................................ 106 3.20 ImageWin Module (Windows-only).................................. 107 3.21 ExifTags Module........................................... 109 3.22 TiffTags Module........................................... 109 i 3.23 PSDraw Module............................................. 110 3.24 PixelAccess Class.......................................... 111 3.25 PyAccess Module........................................... 112 3.26 PIL Package (autodoc of remaining modules).............................. 112 3.27 Plugin reference............................................. 121 3.28 Internal Reference Docs......................................... 138 4 Porting 143 5 About 145 5.1 Goals................................................... 145 5.2 License.................................................. 145 5.3 Why a fork?............................................... 145 5.4 What about PIL?............................................. 145 6 Release Notes 147 6.1 6.1.0................................................... 147 6.2 6.0.0................................................... 149 6.3 5.4.1................................................... 153 6.4 5.4.0................................................... 153 6.5 5.3.0................................................... 155 6.6 5.2.0................................................... 156 6.7 5.1.0................................................... 158 6.8 5.0.0................................................... 158 6.9 4.3.0................................................... 160 6.10 4.2.1................................................... 162 6.11 4.2.0................................................... 162 6.12 4.1.1................................................... 163 6.13 4.1.0................................................... 163 6.14 4.0.0................................................... 164 6.15 3.4.0................................................... 165 6.16 3.3.2................................................... 166 6.17 3.3.0................................................... 167 6.18 3.2.0................................................... 167 6.19 3.1.2................................................... 168 6.20 3.1.1................................................... 169 6.21 3.1.0................................................... 170 6.22 3.0.0................................................... 171 6.23 2.8.0................................................... 172 6.24 2.7.0................................................... 172 7 Deprecations and removals 175 7.1 Deprecated features........................................... 175 7.2 Removed features............................................ 177 8 Indices and tables 179 Python Module Index 181 Index 183 ii Pillow (PIL Fork) Documentation, Release 6.2.0.dev0 Pillow is the friendly PIL fork by Alex Clark and Contributors. PIL is the Python Imaging Library by Fredrik Lundh and Contributors. Contents 1 Pillow (PIL Fork) Documentation, Release 6.2.0.dev0 2 Contents CHAPTER 1 Installation 1.1 Warnings Warning: Pillow and PIL cannot co-exist in the same environment. Before installing Pillow, please uninstall PIL. Warning: Pillow >= 1.0 no longer supports “import Image”. Please use “from PIL import Image” instead. Warning: Pillow >= 2.1.0 no longer supports “import _imaging”. Please use “from PIL.Image import core as _imaging” instead. 1.2 Notes Note: Pillow is supported on the following Python versions Python 2.4 2.5 2.6 2.7 3.2 3.3 3.4 3.5 3.6 3.7 Pillow < 2.0.0 Yes Yes Yes Yes Pillow 2.x - 3.x Yes Yes Yes Yes Yes Yes Pillow 4.x Yes Yes Yes Yes Yes Pillow 5.0.x - 5.1.x Yes Yes Yes Yes Pillow 5.2.x - 5.4.x Yes Yes Yes Yes Yes Pillow 6.x Yes Yes Yes Yes Pillow >= 7.0.0 Yes Yes Yes 3 Pillow (PIL Fork) Documentation, Release 6.2.0.dev0 1.3 Basic Installation Note: The following instructions will install Pillow with support for most common image formats. See External Libraries for a full list of external libraries supported. Install Pillow with pip: $ pip install Pillow 1.3.1 Windows Installation We provide Pillow binaries for Windows compiled for the matrix of supported Pythons in both 32 and 64-bit versions in wheel, egg, and executable installers. These binaries have all of the optional libraries included except for raqm and libimagequant: > pip install Pillow 1.3.2 macOS Installation We provide binaries for macOS for each of the supported Python versions in the wheel format. These include support for all optional libraries except libimagequant. Raqm support requires libraqm, fribidi, and harfbuzz to be installed separately: $ pip install Pillow 1.3.3 Linux Installation We provide binaries for Linux for each of the supported Python versions in the manylinux wheel format. These include support for all optional libraries except libimagequant. Raqm support requires libraqm, fribidi, and harfbuzz to be installed separately: $ pip install Pillow Most major Linux distributions, including Fedora, Debian/Ubuntu and ArchLinux also include Pillow in packages that previously contained PIL e.g. python-imaging. 1.3.4 FreeBSD Installation Pillow can be installed on FreeBSD via the official Ports or Packages systems: Ports: $ cd /usr/ports/graphics/py-pillow && make install clean Packages: $ pkg install py27-pillow 4 Chapter 1. Installation Pillow (PIL Fork) Documentation, Release 6.2.0.dev0 Note: The Pillow FreeBSD port and packages are tested by the ports team with all supported FreeBSD versions and against Python 2.7 and 3.x. 1.4 Building From Source Download and extract the compressed archive from PyPI. 1.4.1 External Libraries Note: You do not need to install all supported external libraries to use Pillow’s basic features. Zlib and libjpeg are required by default. Note: There are scripts to install the dependencies for some operating systems included in the depends directory. Also see the Dockerfiles in our docker images repo. Many of Pillow’s features require external libraries: • libjpeg provides JPEG functionality. – Pillow has been tested with libjpeg versions 6b, 8, 9-9c and libjpeg-turbo version 8. – Starting with Pillow 3.0.0, libjpeg is required by default, but may be disabled with the --disable-jpeg flag. • zlib provides access to compressed PNGs – Starting with Pillow 3.0.0, zlib is required by default, but may be disabled with the --disable-zlib flag. • libtiff provides compressed TIFF functionality – Pillow has been tested with libtiff versions 3.x and 4.0 • libfreetype provides type related services • littlecms provides color management – Pillow version 2.2.1 and below uses liblcms1, Pillow 2.3.0 and above uses liblcms2. Tested with 1.19 and 2.7-2.9. • libwebp provides the WebP format. – Pillow has been tested with version 0.1.3, which does not read transparent WebP files. Versions 0.3.0 and above support transparency. • tcl/tk provides support for tkinter bitmap and photo images. • openjpeg provides JPEG 2000 functionality. – Pillow has been tested with openjpeg 2.0.0, 2.1.0 and 2.3.1. – Pillow does not support the earlier 1.5 series which ships with Debian Jessie. • libimagequant provides improved color quantization 1.4. Building From Source 5 Pillow (PIL Fork) Documentation, Release 6.2.0.dev0 – Pillow has been tested with libimagequant 2.6-2.12.3 – Libimagequant is licensed GPLv3, which is more restrictive than the Pillow license, therefore we will not be distributing binaries with libimagequant support enabled. – Windows support: Libimagequant requires VS2015/MSVC 19