# python-pillow/pillow architecture

> Architecture diagram of the GitHub repository python-pillow/pillow, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/python-pillow/pillow
- Repository: https://github.com/python-pillow/pillow

## Overview

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: [`src/PIL/__init__.py`](https://github.com/python-pillow/pillow/blob/main/src/PIL/__init__.py) (PIL package), [`src/libImaging/Imaging.h`](https://github.com/python-pillow/pillow/blob/main/src/libImaging/Imaging.h) (libImaging), [`src/PIL/Image.py`](https://github.com/python-pillow/pillow/blob/main/src/PIL/Image.py) (Image core), [`src/_imagingcms.c`](https://github.com/python-pillow/pillow/blob/main/src/_imagingcms.c) (Native ext)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_public["Python API"]
  node_src_pil_init["PIL package<br/>public API package<br/>[__init__.py]"]
  node_src_pil_image["Image core<br/>image abstraction<br/>[Image.py]"]
  node_src_pil_file["File layer<br/>I/O and loader base<br/>[ImageFile.py]"]
  node_src_pil_draw_ops["Draw & ops<br/>image ops<br/>[ImageDraw.py]"]
  node_src_pil_font["Fonts<br/>text and font API<br/>[ImageFont.py]"]
  node_src_pil_metadata["Metadata<br/>tags and color<br/>[ExifTags.py]"]
end

subgraph group_g_native["Native core"]
  node_src_imaging_c["_imaging<br/>C extension bridge<br/>[_imaging.c]"]
  node_src_imaging_ext["Native ext<br/>optional C extensions<br/>[_imagingcms.c]"]
  node_src_libimaging["libImaging<br/>shared C engine<br/>[Imaging.h]"]
end

subgraph group_g_formats["Format plugins"]
  node_src_pil_plugins_raster["Raster plugins<br/>image format plugins<br/>[PngImagePlugin.py]"]
  node_src_pil_plugins_archive["Container plugins<br/>container and document plugins<br/>[TiffImagePlugin.py]"]
  node_src_pil_plugins_special["Special plugins<br/>specialized plugins<br/>[WmfImagePlugin.py]"]
end

subgraph group_g_integrations["Integrations"]
  node_src_tk_bridge["Tk bridge<br/>GUI bridge<br/>[tkImaging.c]"]
  node_src_thirdparty["Third-party shims<br/>vendored native deps<br/>[raqm.c]"]
end

subgraph group_g_tooling["Tooling"]
  node_tests[("Tests<br/>test suite")]
  node_checks(("Checks"))
  node_build["Build system<br/>packaging and build<br/>[pyproject.toml]"]
  node_docs["Docs<br/>documentation<br/>[index.rst]"]
end

node_src_pil_init -->|"exports"| node_src_pil_image
node_src_pil_init -->|"routes I/O"| node_src_pil_file
node_src_pil_init -->|"registers"| node_src_pil_plugins_raster
node_src_pil_init -->|"registers"| node_src_pil_plugins_archive
node_src_pil_init -->|"registers"| node_src_pil_plugins_special
node_src_pil_image -->|"loads/saves via"| node_src_pil_file
node_src_pil_image -->|"calls native"| node_src_imaging_c
node_src_pil_draw_ops -->|"uses engine"| node_src_libimaging
node_src_pil_font -->|"uses"| node_src_imaging_ext
node_src_pil_metadata -->|"annotates"| node_src_pil_image
node_src_pil_plugins_raster -->|"implements"| node_src_pil_file
node_src_pil_plugins_raster -->|"delegates pixels"| node_src_libimaging
node_src_pil_plugins_archive -->|"delegates pixels"| node_src_libimaging
node_src_pil_plugins_special -->|"binds to"| node_src_imaging_ext
node_src_imaging_c -->|"bridges to"| node_src_libimaging
node_src_imaging_ext -->|"wraps"| node_src_thirdparty
node_src_pil_font -.->|"optional shaping"| node_src_thirdparty
node_src_pil_init -->|"integrates"| node_src_tk_bridge
node_tests -->|"exercises"| node_src_pil_init
node_tests -->|"stress tests"| node_src_libimaging
node_checks -.->|"focuses"| node_tests
node_build -->|"compiles"| node_src_imaging_c
node_build -->|"packages"| node_src_imaging_ext
node_build -->|"ships"| node_src_libimaging
node_docs -->|"documents"| node_src_pil_init
node_docs -->|"documents"| node_src_libimaging

click node_src_pil_init "https://github.com/python-pillow/pillow/blob/main/src/PIL/__init__.py"
click node_src_pil_image "https://github.com/python-pillow/pillow/blob/main/src/PIL/Image.py"
click node_src_pil_file "https://github.com/python-pillow/pillow/blob/main/src/PIL/ImageFile.py"
click node_src_pil_draw_ops "https://github.com/python-pillow/pillow/blob/main/src/PIL/ImageDraw.py"
click node_src_pil_font "https://github.com/python-pillow/pillow/blob/main/src/PIL/ImageFont.py"
click node_src_pil_metadata "https://github.com/python-pillow/pillow/blob/main/src/PIL/ExifTags.py"
click node_src_pil_plugins_raster "https://github.com/python-pillow/pillow/blob/main/src/PIL/PngImagePlugin.py"
click node_src_pil_plugins_archive "https://github.com/python-pillow/pillow/blob/main/src/PIL/TiffImagePlugin.py"
click node_src_pil_plugins_special "https://github.com/python-pillow/pillow/blob/main/src/PIL/WmfImagePlugin.py"
click node_src_imaging_c "https://github.com/python-pillow/pillow/blob/main/src/_imaging.c"
click node_src_imaging_ext "https://github.com/python-pillow/pillow/blob/main/src/_imagingcms.c"
click node_src_libimaging "https://github.com/python-pillow/pillow/blob/main/src/libImaging/Imaging.h"
click node_src_tk_bridge "https://github.com/python-pillow/pillow/blob/main/src/Tk/tkImaging.c"
click node_src_thirdparty "https://github.com/python-pillow/pillow/blob/main/src/thirdparty/raqm/raqm.c"
click node_tests "https://github.com/python-pillow/pillow/tree/main/Tests"
click node_checks "https://github.com/python-pillow/pillow/tree/main/checks"
click node_build "https://github.com/python-pillow/pillow/blob/main/pyproject.toml"
click node_docs "https://github.com/python-pillow/pillow/blob/main/docs/index.rst"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_src_pil_init,node_src_pil_image,node_src_pil_file,node_src_pil_draw_ops,node_src_pil_font,node_src_pil_metadata toneBlue
class node_src_imaging_c,node_src_imaging_ext,node_src_libimaging toneAmber
class node_src_pil_plugins_raster,node_src_pil_plugins_archive,node_src_pil_plugins_special toneMint
class node_src_tk_bridge,node_src_thirdparty toneRose
class node_tests,node_checks,node_build,node_docs toneIndigo
```

## Components

### Python API

User-facing modules and image abstractions imported by applications.

- [PIL package](https://github.com/python-pillow/pillow/blob/main/src/PIL/__init__.py): public API package · Top-level Python package that exposes Pillow’s user-facing surface and plugin registry. · `src/PIL/__init__.py`
- [Image core](https://github.com/python-pillow/pillow/blob/main/src/PIL/Image.py): image abstraction · Central Image object and most of the Python-side image lifecycle and operations. · `src/PIL/Image.py`
- [File layer](https://github.com/python-pillow/pillow/blob/main/src/PIL/ImageFile.py): I/O and loader base · Shared file/decoder infrastructure used by plugins and higher-level image operations. · `src/PIL/ImageFile.py`
- [Draw & ops](https://github.com/python-pillow/pillow/blob/main/src/PIL/ImageDraw.py): image ops · Common compositing, drawing, filtering, and transformation helpers exposed to Python. · `src/PIL/ImageDraw.py`
- [Fonts](https://github.com/python-pillow/pillow/blob/main/src/PIL/ImageFont.py): text and font API · Font loading and text rendering interface for rasterizing text into images. · `src/PIL/ImageFont.py`
- [Metadata](https://github.com/python-pillow/pillow/blob/main/src/PIL/ExifTags.py): tags and color · 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](https://github.com/python-pillow/pillow/blob/main/src/_imaging.c): C extension bridge · Primary native extension connecting Python objects to the imaging core. · `src/_imaging.c`
- [Native ext](https://github.com/python-pillow/pillow/blob/main/src/_imagingcms.c): optional C extensions · Supplementary native modules for CMS, FreeType, math, morphology, Tk, WebP, and AVIF. · `src/_imagingcms.c`
- [libImaging](https://github.com/python-pillow/pillow/blob/main/src/libImaging/Imaging.h): shared C engine · 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](https://github.com/python-pillow/pillow/blob/main/src/PIL/PngImagePlugin.py): image format plugins · Representative format handlers for common raster codecs and incremental loading/saving. · `src/PIL/PngImagePlugin.py`
- [Container plugins](https://github.com/python-pillow/pillow/blob/main/src/PIL/TiffImagePlugin.py): container and document plugins · Plugins for multi-frame, archive-like, and document-oriented image containers. · `src/PIL/TiffImagePlugin.py`
- [Special plugins](https://github.com/python-pillow/pillow/blob/main/src/PIL/WmfImagePlugin.py): specialized 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](https://github.com/python-pillow/pillow/blob/main/src/Tk/tkImaging.c): GUI bridge · Tk-specific native bridge used by ImageTk and Tk image integration. · `src/Tk/tkImaging.c`
- [Third-party shims](https://github.com/python-pillow/pillow/blob/main/src/thirdparty/raqm/raqm.c): vendored native deps · 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](https://github.com/python-pillow/pillow/tree/main/Tests): test suite · Large format-focused regression, robustness, and fuzzing-oriented test corpus. · `Tests`
- [Checks](https://github.com/python-pillow/pillow/tree/main/checks): security checks · Targeted scripts for crash reproduction, fuzz regressions, and safety checks. · `checks`
- [Build system](https://github.com/python-pillow/pillow/blob/main/pyproject.toml): packaging and build · Packaging, wheel, and native build orchestration for distributed artifacts. · `pyproject.toml`
- [Docs](https://github.com/python-pillow/pillow/blob/main/docs/index.rst): documentation · User, handbook, reference, and design documentation for the library and internals. · `docs/index.rst`

## Connections

- 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.
