How python-pillow/pillow works
1. What this repository is
Pillow is a Python imaging library with a layered architecture: a pure-Python public API, performance-critical C extensions, and a shared C core for pixel storage and image processing. It is packaged as a Python distribution but ships native code and optional bindings to external codec/font libraries.
2. Public API boundary
The main entry point is src/PIL, which exposes user-facing modules such as Image, ImageDraw, ImageFilter, ImageFont, ImageOps, ImageCms, ImageQt, ImageTk, and many format-specific plugins. This layer is what Python applications import; it hides the native implementation details and coordinates I/O, mode conversion, and plugin dispatch.
3. Image object and internal data flow
The central runtime object is the Image abstraction in src/PIL/Image.py. Typical flow is: bytes/file-like object → plugin open()/decoder → internal image buffer → manipulation via Python APIs and C-backed helpers → encoder/plugin save() back to a file-like object. The core design is optimized around a few basic pixel formats and fast access to contiguous image data.
4. C extension layer
src/_imaging.c and related extension modules (_imagingcms, _imagingft, _imagingmath, _imagingmorph, _imagingtk, _webp, _avif) expose native functionality to Python. These extensions provide the bridge from Python objects to the C imaging core and to external libraries for color management, text rendering, GUI/Tk support, WebP, and AVIF.
5. Shared imaging engine
src/libImaging is the low-level engine that implements pixel storage, format conversion, resampling, filters, compositing, quantization, and many codecs. This is the main computation boundary: Python code and plugins call into this library for actual pixel operations, while format plugins focus on parsing and serialization. The code here is mostly format-agnostic and operates on internal buffers.
6. Format plugin architecture
Image formats are implemented as separate plugin modules under src/PIL such as JpegImagePlugin, PngImagePlugin, TiffImagePlugin, GifImagePlugin, WebPImagePlugin, AvifImagePlugin, BmpImagePlugin, PsdImagePlugin, and many more. Each plugin handles format-specific headers, metadata, incremental loading, and encoder/decoder setup, then delegates pixel work to the core C library or external codecs.
7. Optional external codec and library integrations
The project can link against or bundle libraries such as libjpeg, libpng, libtiff, openjpeg, libwebp, libavif, freetype, littlecms2, and raqm. These integrations materially affect architecture because they provide format decoding/encoding, color management, and text shaping. The repo includes shims and vendored code where needed, such as src/thirdparty/raqm and src/thirdparty/fribidi-shim.
8. Text, fonts, and rendering subsystems
Fonts and layout are handled through ImageFont, FontFile, BdfFontFile, PcfFontFile, and native font bindings. Text rendering can flow through FreeType and optionally shaping libraries for complex scripts. GUI-adjacent modules like ImageTk, ImageQt, ImageWin, and ImageGrab are separate integration boundaries rather than core image-processing paths.
9. Metadata, color, and utility subsystems
Several modules handle non-pixel concerns: ExifTags, TiffTags, ImageCms, ImageColor, ImagePalette, PdfParser, TarIO, ContainerIO, and ImageSequence. These modules sit alongside the main image pipeline to manage metadata parsing, color transforms, multi-frame images, and container-like file access.
10. Testing and security posture
Tests is extremely large and format-oriented, with fixture images covering valid cases, edge cases, crashes, malformed inputs, and regressions. There are also fuzzing assets under Tests/oss-fuzz and targeted security checks in checks/. This reflects a library architecture focused on input hardening, parser robustness, and codec safety.
11. Build, packaging, and release pipeline
Packaging is driven by pyproject.toml, setup.py, and _custom_build/backend.py, with wheel and platform-specific build support in wheels/ and winbuild/. CI scripts and GitHub workflows exercise linting, tests, wheels, docs, fuzzing, and platform matrix builds. Native compilation is a first-class concern because the distributable artifact includes C extensions and optional bundled dependencies.
12. Documentation and project governance
docs/ contains the architectural and user-facing documentation, including internal design notes, plugin documentation, and format handbooks. This repo also includes release, security, and contribution workflows, but those are support systems around the core library rather than runtime architecture.
Main entry points: __init__.py PIL package · Imaging.h libImaging · Image.py Image core · _imagingcms.c Native ext
Components 18
Python API
User-facing modules and image abstractions imported by applications.
- PIL package · Top-level Python package that exposes Pillow’s user-facing surface and plugin registry.
src/PIL/__init__.py - Image core · Central Image object and most of the Python-side image lifecycle and operations.
src/PIL/Image.py - File layer · Shared file/decoder infrastructure used by plugins and higher-level image operations.
src/PIL/ImageFile.py - Draw & ops · Common compositing, drawing, filtering, and transformation helpers exposed to Python.
src/PIL/ImageDraw.py - Fonts · Font loading and text rendering interface for rasterizing text into images.
src/PIL/ImageFont.py - Metadata · Non-pixel helpers for EXIF, TIFF tags, color transforms, palettes, and image sequences.
src/PIL/ExifTags.py
Native core
C extensions and shared imaging engine that do the pixel work.
- _imaging · Primary native extension connecting Python objects to the imaging core.
src/_imaging.c - Native ext · Supplementary native modules for CMS, FreeType, math, morphology, Tk, WebP, and AVIF.
src/_imagingcms.c - libImaging · Low-level pixel storage, conversion, filtering, resampling, codecs, and core image algorithms.
src/libImaging/Imaging.h
Format plugins
Format-specific loaders and savers that parse headers and delegate image operations.
- Raster plugins · Representative format handlers for common raster codecs and incremental loading/saving.
src/PIL/PngImagePlugin.py - Container plugins · Plugins for multi-frame, archive-like, and document-oriented image containers.
src/PIL/TiffImagePlugin.py - Special plugins · Plugins for less common formats and integration-oriented image sources.
src/PIL/WmfImagePlugin.py
Integrations
Optional external codecs, font engines, and GUI-adjacent bridges.
- Tk bridge · Tk-specific native bridge used by ImageTk and Tk image integration.
src/Tk/tkImaging.c - Third-party shims · Bundled compatibility layers and vendored code for optional external dependencies.
src/thirdparty/raqm/raqm.c
Tooling
Tests, checks, packaging, docs, and release/build support.
- Tests · Large format-focused regression, robustness, and fuzzing-oriented test corpus.
Tests - Checks · Targeted scripts for crash reproduction, fuzz regressions, and safety checks.
checks - Build system · Packaging, wheel, and native build orchestration for distributed artifacts.
pyproject.toml - Docs · User, handbook, reference, and design documentation for the library and internals.
docs/index.rst
Connections 26
- PIL package → Image core: exports · Public package exposes the central Image API.
- PIL package → File layer: routes I/O · Package initialization wires plugin and file handling infrastructure.
- PIL package → Raster plugins: registers · Package exposes common format plugins.
- PIL package → Container plugins: registers · Package exposes container and multipage plugins.
- PIL package → Special plugins: registers · Package exposes specialized and integration-oriented plugins.
- Image core → File layer: loads/saves via · Image objects use shared file machinery for decode and encode workflows.
- Image core → _imaging: calls native · Core image operations delegate into the main C extension.
- Draw & ops → libImaging: uses engine · Drawing, filtering, and transforms rely on the shared C core.
- Fonts → Native ext: uses · Font rendering depends on native text and FreeType-related bindings.
- Metadata → Image core: annotates · Metadata helpers complement the main Image abstraction.
- Raster plugins → File layer: implements · Plugins implement format-specific open/load/save on the shared file layer.
- Raster plugins → libImaging: delegates pixels · Raster codecs hand pixel work to the core engine and codec helpers.
- Container plugins → libImaging: delegates pixels · Container and document formats use the shared imaging core for raster work.
- Special plugins → Native ext: binds to · Special plugins depend on optional native integrations for external formats and platforms.
- _imaging → libImaging: bridges to · Primary extension is the boundary between Python and the low-level engine.
- Native ext → Third-party shims: wraps · Optional extensions are supported by vendored compatibility and dependency shims.
- Fonts → Third-party shims: optional shaping · Text rendering can use bundled shaping support where available.
- PIL package → Tk bridge: integrates · Tk support is exposed through the public package and ImageTk module.
- Tests → PIL package: exercises · Tests validate the public API and plugin behavior.
- Tests → libImaging: stress tests · Robustness tests cover the native imaging engine and codecs.
- Checks → Tests: focuses · Targeted checks extend crash, fuzz, and security coverage.
- Build system → _imaging: compiles · Build tooling produces native extension modules.
- Build system → Native ext: packages · Build tooling also bundles optional native integrations.
- Build system → libImaging: ships · Distribution includes the shared C engine.
- Docs → PIL package: documents · Documentation explains the public package and user-facing API.
- Docs → libImaging: documents · Internal docs describe the native imaging core and architecture.