0
# Pillow (PIL)
1

2
Pillow is a comprehensive Python imaging library that serves as the friendly fork of the Python Imaging Library (PIL), providing extensive image processing capabilities for Python applications. It offers robust file format support for reading, writing, and manipulating images across dozens of formats including JPEG, PNG, TIFF, GIF, BMP, and many specialized formats, with efficient internal representation optimized for performance.
3

4
## Package Information
5

6
- **Package Name**: pillow
7
- **Language**: Python
8
- **Installation**: `pip install pillow`
9

10
## Core Imports
11

12
```python
13
from PIL import Image
14
```
15

16
Common for working with specific functionality:
17

18
```python
19
from PIL import Image, ImageDraw, ImageFilter, ImageFont, ImageOps
20
from PIL import ImageChops, ImageColor, ImageStat, ImageSequence
21
```
22

23
For specialized tasks:
24

25
```python
26
from PIL import ImageEnhance, ImageCms, ExifTags, TiffTags
27
```
28

29
## Basic Usage
30

31
```python
32
from PIL import Image
33

34
# Open an image
35
image = Image.open("example.jpg")
36

37
# Get basic info
38
print(f"Size: {image.size}")
39
print(f"Mode: {image.mode}")
40
print(f"Format: {image.format}")
41

42
# Basic operations
43
resized = image.resize((800, 600))
44
rotated = image.rotate(90)
45
converted = image.convert("L")  # Convert to grayscale
46

47
# Save the image
48
resized.save("resized_example.jpg")
49

50
# Create a new image
51
new_image = Image.new("RGB", (400, 300), color="red")
52
new_image.save("red_rectangle.png")
53
```
54

55
## Architecture
56

57
Pillow's architecture centers around the Image class as the primary interface for image manipulation:
58

59
- **Image Class**: Core object representing image data with methods for manipulation, conversion, and I/O operations
60
- **Format Plugins**: Modular system supporting 40+ image formats through dedicated plugin modules
61
- **Drawing Subsystem**: Vector graphics capabilities through ImageDraw for creating and annotating images
62
- **Filter System**: Extensible filtering framework for image enhancement and effects
63
- **Color Management**: Comprehensive color space handling and ICC profile support
64
- **Font Rendering**: TrueType/OpenType font support for text rendering on images
65

66
This design provides maximum compatibility across image formats while maintaining performance through C extensions for critical operations.
67

68
## Capabilities
69

70
### Core Image Operations
71

72
Essential image manipulation functions including opening, creating, resizing, rotating, cropping, and format conversion. The Image class provides the foundation for all image operations.
73

74
```python { .api }
75
def open(fp, mode="r", formats=None): ...
76
def new(mode, size, color=0): ...
77

78
class Image:
79
    def resize(self, size, resample=None, box=None, reducing_gap=None): ...
80
    def rotate(self, angle, resample=0, expand=0, center=None, translate=None, fillcolor=None): ...
81
    def crop(self, box=None): ...
82
    def convert(self, mode=None, matrix=None, dither=None, palette=0, colors=256): ...
83
    def save(self, fp, format=None, **params): ...
84
```
85

86
[Core Image Operations](./core-image.md)
87

88
### Drawing and Graphics
89

90
Vector graphics capabilities for drawing shapes, text, and other graphical elements on images. Supports various drawing primitives and text rendering with font support.
91

92
```python { .api }
93
def Draw(im, mode=None): ...
94

95
class ImageDraw:
96
    def line(self, xy, fill=None, width=0, joint=None): ...
97
    def rectangle(self, xy, fill=None, outline=None, width=1): ...
98
    def ellipse(self, xy, fill=None, outline=None, width=1): ...
99
    def polygon(self, xy, fill=None, outline=None, width=1): ...
100
    def text(self, xy, text, fill=None, font=None, anchor=None, spacing=4, align="left", direction=None, features=None, language=None, stroke_width=0, stroke_fill=None, embedded_color=False): ...
101
```
102

103
[Drawing and Graphics](./drawing.md)
104

105
### Image Filters and Enhancement
106

107
Comprehensive filtering system for image enhancement, blur effects, edge detection, and artistic effects. Includes both built-in filters and custom filter creation capabilities.
108

109
```python { .api }
110
class Filter: ...
111
class GaussianBlur(MultibandFilter): ...
112
class UnsharpMask(MultibandFilter): ...
113

114
# Built-in filter instances
115
BLUR: Filter
116
CONTOUR: Filter
117
DETAIL: Filter
118
EDGE_ENHANCE: Filter
119
SHARPEN: Filter
120
```
121

122
[Image Filters](./filters.md)
123

124
### Font Handling and Text
125

126
TrueType and OpenType font support for rendering text on images with full typography control including size, spacing, alignment, and styling options.
127

128
```python { .api }
129
def load_default(size=None): ...
130
def truetype(font=None, size=10, index=0, encoding="", layout_engine=None): ...
131

132
class FreeTypeFont:
133
    def getsize(self, text, direction=None, features=None, language=None, stroke_width=0): ...
134
    def getmask(self, text, mode="", direction=None, features=None, language=None, stroke_width=0, anchor=None, ink=0, start=None): ...
135
```
136

137
[Font Handling](./fonts.md)
138

139
### Image Operations and Transformations
140

141
Advanced image manipulation functions including automatic contrast adjustment, color space operations, geometric transformations, and specialized processing operations.
142

143
```python { .api }
144
def autocontrast(image, cutoff=0, ignore=None, mask=None, preserve_tone=False): ...
145
def equalize(image, mask=None): ...
146
def fit(image, size, method=3, bleed=0.0, centering=(0.5, 0.5)): ...
147
def grayscale(image): ...
148
def invert(image): ...
149
def posterize(image, bits): ...
150
def solarize(image, threshold=128): ...
151
```
152

153
[Image Operations](./operations.md)
154

155
### Color Management
156

157
Professional color management with ICC profile support, color space conversions, and rendering intent control for accurate color reproduction across devices and media.
158

159
```python { .api }
160
def profileToProfile(im, inputProfile, outputProfile, renderingIntent=0, outputMode=None, inPlace=False, flags=0): ...
161
def buildTransform(inputProfile, outputProfile, inMode, outMode, renderingIntent=0, flags=0): ...
162
def createProfile(colorSpace, colorTemp=None): ...
163

164
class ImageCmsProfile: ...
165
class ImageCmsTransform: ...
166
```
167

168
[Color Management](./color-management.md)
169

170
### Image Enhancement
171

172
Systematic image quality improvement through brightness, contrast, color saturation, and sharpness adjustments with intuitive enhancement classes.
173

174
```python { .api }
175
class Color:
176
    def enhance(self, factor): ...
177

178
class Contrast:
179
    def enhance(self, factor): ...
180

181
class Brightness:
182
    def enhance(self, factor): ...
183

184
class Sharpness:
185
    def enhance(self, factor): ...
186
```
187

188
[Image Enhancement](./enhancement.md)
189

190
### Mathematical Operations
191

192
Pixel-level mathematical operations between images including blending, compositing, arithmetic operations, logical operations, and advanced blend modes for comprehensive image processing workflows.
193

194
```python { .api }
195
def add(image1, image2, scale=1.0, offset=0): ...
196
def subtract(image1, image2, scale=1.0, offset=0): ...
197
def multiply(image1, image2): ...
198
def blend(image1, image2, alpha): ...
199
def composite(image1, image2, mask): ...
200
def difference(image1, image2): ...
201
def screen(image1, image2): ...
202
def overlay(image1, image2): ...
203
def logical_and(image1, image2): ...
204
def offset(image, xoffset, yoffset=None): ...
205
```
206

207
[Mathematical Operations](./math-operations.md)
208

209
### Color Utilities
210

211
Comprehensive color conversion and name resolution utilities for handling CSS-style color strings, named colors, and conversion between different color formats and image modes.
212

213
```python { .api }
214
def getrgb(color: str) -> tuple[int, int, int] | tuple[int, int, int, int]: ...
215
def getcolor(color: str, mode: str) -> int | tuple[int, ...]: ...
216
```
217

218
[Color Utilities](./color-utilities.md)
219

220
### Image Statistics
221

222
Statistical analysis capabilities for images providing detailed metrics about pixel distributions, central tendencies, and variability across image bands.
223

224
```python { .api }
225
class Stat:
226
    def __init__(self, image_or_list, mask=None): ...
227
    @property
228
    def mean(self) -> list[float]: ...
229
    @property
230
    def median(self) -> list[int]: ...
231
    @property
232
    def extrema(self) -> list[tuple[int, int]]: ...
233
    @property
234
    def var(self) -> list[float]: ...
235
    @property
236
    def stddev(self) -> list[float]: ...
237
```
238

239
[Image Statistics](./image-statistics.md)
240

241
### Image Sequences
242

243
Animation and multi-frame image support for iterating through frames in animated GIFs, multi-page TIFFs, and other sequence-based image formats.
244

245
```python { .api }
246
class Iterator:
247
    def __init__(self, im: Image.Image): ...
248
    def __getitem__(self, ix: int) -> Image.Image: ...
249
    def __iter__(self) -> Iterator: ...
250
    def __next__(self) -> Image.Image: ...
251

252
def all_frames(im, func=None) -> list[Image.Image]: ...
253
```
254

255
[Image Sequences](./image-sequences.md)
256

257
## Constants and Enums
258

259
### Image Modes
260
- `"1"` - 1-bit pixels, black and white, stored as 8 bits per pixel
261
- `"L"` - 8-bit pixels, black and white  
262
- `"P"` - 8-bit pixels, mapped to any other mode using a color palette
263
- `"RGB"` - 3x8-bit pixels, true color
264
- `"RGBA"` - 4x8-bit pixels, true color with transparency mask
265
- `"CMYK"` - 4x8-bit pixels, color separation
266
- `"YCbCr"` - 3x8-bit pixels, color video format
267
- `"LAB"` - 3x8-bit pixels, the L*a*b* color space
268
- `"HSV"` - 3x8-bit pixels, Hue, Saturation, Value color space
269

270
### Resampling Filters
271
```python { .api }
272
class Resampling(IntEnum):
273
    NEAREST = 0
274
    BILINEAR = 1
275
    BICUBIC = 2
276
    LANCZOS = 3
277
    BOX = 4
278
    HAMMING = 5
279
```
280

281
### Transform Types
282
```python { .api }
283
class Transform(IntEnum):
284
    AFFINE = 0
285
    EXTENT = 1
286
    PERSPECTIVE = 2
287
    QUAD = 3
288
    MESH = 4
289
```
290

291
### Transpose Operations
292
```python { .api }
293
class Transpose(IntEnum):
294
    FLIP_LEFT_RIGHT = 0
295
    FLIP_TOP_BOTTOM = 1
296
    ROT_90 = 2
297
    ROT_180 = 3
298
    ROT_270 = 4
299
    TRANSPOSE = 5
300
    TRANSVERSE = 6
301
```