---

name: plugins-and-extension description: "Extend Pillow with custom image plugins, diagnose plugin registration/open dispatch problems, and inspect optional codec/feature support for advanced integrations." disable-model-invocation: true metadata: disco-role: operating license: NOASSERTION

Pillow Plugins and Extension

Use this sub-skill when you need to add a custom Pillow image plugin, debug why Image.open() is not dispatching to a plugin, understand the boundary between Python plugin code and decoder backends, or inspect optional feature/codec support. For everyday open/save usage and metadata options, use the root skill's formats guidance instead.

Core Model

Pillow image loading is plugin-driven:

1. A plugin module registers a format with PIL.Image.register_open(format_id, factory, accept).
2. Image.open(fp, mode="r", formats=None) reads the first 16 bytes and calls each loaded plugin's accept(prefix) function in registry order.
3. When accept returns truthy, Pillow constructs the registered ImageFile.ImageFile subclass and calls its _open() method.
4. _open() parses only enough header data to set image metadata and tile descriptors; actual pixels are decoded later when load(), pixel access, conversion, or saving needs the data.
5. ImageFile.load() sorts tile descriptors, creates the requested decoder, seeks to tile offsets, and feeds bytes to the decoder.

Important consequence: a new plugin must be imported before it can participate in dispatch. Pillow does not automatically import arbitrary *ImagePlugin.py files from sys.path.

Minimal Plugin Checklist

For a read plugin:

• Create a module named like XxxImagePlugin.py or another importable module name used by your package.
• Define a narrow, cheap _accept(prefix: bytes) that inspects only the available prefix bytes.
• Subclass PIL.ImageFile.ImageFile.
• Set class attributes format = "FORMAT" and format_description = "Human description".
• In _open(), validate the header, set self._size = (width, height), set self._mode = "L", "RGB", or another valid Pillow mode, and set self.tile if the image can be loaded.
• Register with Image.register_open(format, ImageFileSubclass, _accept).
• Register extensions with Image.register_extension(format, ".ext") or Image.register_extensions(format, [".ext", ...]).
• Import the plugin before calling Image.open() unless it is packaged so the application imports it during startup.

Use scripts/minimal_spam_plugin.py as a self-contained working example. It registers a trivial raw SPAM format and has --self-test to create and open a tiny fixture without relying on repository files.

Tile Boundary

A tile descriptor tells ImageFile.load() how to decode bytes into a rectangular region. Use ImageFile._Tile(codec_name, extents, offset, args):

• codec_name: a decoder name such as "raw", "jpeg", "zip", or a registered Python decoder name.
• extents: (left, top, right, bottom) in image coordinates, usually (0, 0) + self.size for one full-image tile.
• offset: byte offset from the start of the file to the encoded image data.
• args: decoder-specific parameters. For the raw decoder, use (raw_mode, stride, orientation); common simple case is (self.mode, 0, 1).

Python plugins can parse headers and route bytes to existing decoders. They cannot magically add support for a compressed bitstream that Pillow has no decoder for; use an existing decoder, implement a Python ImageFile.PyDecoder, or provide/enable a C extension codec when performance or codec availability requires it.

Feature and CLI Inspection

Use PIL.features and python -m PIL to diagnose environment-dependent support:

from PIL import features
print(features.check("jpg"))
print(features.check("webp"))
print(features.version("littlecms2"))
print(features.get_supported())

• python -m PIL prints Pillow build information and supported formats.
• python -m PIL --report prints the report without the verbose supported-format listing.
• features.check(name) accepts module, codec, or feature names such as pil, freetype2, littlecms2, webp, avif, jpg, jpg_2000, zlib, libtiff, raqm, libjpeg_turbo, and xcb.
• Optional codec absence explains failures for plugins that delegate to compiled decoders, for example JPEG 2000, TIFF, WebP, or AVIF.

Debugging Flow

1. Confirm the plugin module is imported before Image.open().
2. Check the format id is uppercase-consistent in registrations and class format.
3. Check _accept(prefix) returns truthy for a valid file and falsey for unrelated files.
4. Open with formats=["FORMAT"] to isolate registry-order effects.
5. Confirm _open() sets valid _size, _mode, and tile before returning.
6. Confirm tile offset and raw mode match the file layout.
7. Call im.load() in tests so decoder errors appear instead of only header-identification success.
8. Use python -m PIL or features.check() when the plugin depends on optional compiled support.

References

• references/custom-plugin-pattern.md gives the authoring pattern and packaging/import guidance.
• references/plugin-api-reference.md summarizes the registry, ImageFile, tile, decoder, and features APIs.
• references/troubleshooting.md maps common plugin failures to fixes.
• scripts/minimal_spam_plugin.py is an executable reference plugin and self-test.